Deploying to Heroku

It’s easy to test and deploy Heroku applications from your Buildkite pipelines.

For GitHub based pipelines you can use Heroku’s Automatic Deploys feature to have a branch deployed once Buildkite has marked the commit as having passed. To get started with automatic deploys: enable it in your Heroku dashboard, check “Wait for CI to pass before deploy”, and when Heroku sees the passing Buildkite commit status it will automatically perform a slug deploy. You can also auto-deploy pull requests using Review Apps.

If you don’t use GitHub or need more control of deployments, this guide will run you through the steps required for performing a manual deployment using git push. You can also use these methods to create pipelines for heroku cli tasks you'd like to automate.

Setting up the Heroku Command Line Interface (CLI)

Estimated time: 5-8 minutes

You can deploy to Heroku using the same git push command you’d run from your development machine.

First step is installing the Heroku CLI on your Buildkite agent machine. For example, this is how you’d do it on a linux agent machine:

$ wget -O- https://toolbelt.heroku.com/install-ubuntu.sh | sh

You can find OSX and Windows installers here.

And now verify it installed correctly by checking the version:

$ heroku --version

You should see version numbers for both the heroku-toolbelt and heroku-cli packages.

The next step is to login using the CLI and your Heroku credentials. We recommend creating a new user in Heroku just for this machine (a “machine user”). Creating a machine user in Heroku is simple: sign up to Heroku as a new user and then add that user as a collaborator to your existing Heroku application.

If you’re ready to login with the Heroku user credentials, make sure you’re running as your buildkite-agent user (which for most packages is “buildkite-agent”) and then run the heroku login command:

$ sudo su buildkite-agent
$ heroku login

You’re now ready to run heroku commands in your Buildkite pipelines! 🎉

Setting up your build pipeline

In your pipeline setup, add a command step. Limit it to the branch you want to deploy, and have it run the following command:

heroku git:remote --app my-app
git push heroku "$BUILDKITE_COMMIT":master

It should look like this:

Buildkite pipeline heroku deploy step

What’s happening here? heroku git:remote ensures the Git remote is always pointing to the correct Heroku application and doesn’t have an old value from previous builds. The git push specifies the exact commit, to make sure we’re pushing the commit we’ve just tested.

Running a build

Once you’ve saved the pipeline settings the final step is to push a commit to master and watch it automatically deploy to Heroku:

Buildkite Heroku deploy success

Post-deploy scripts

If you want to run post-deploy tasks on Heroku simply a waiter and another command step, for example:

heroku git:remote --app my-app
heroku run echo "A post-deploy command"