This guide shows you how to use Semaphore to set up deployment to Heroku for an application or microservice written in any language.
For this guide you will need:
- A working Semaphore project with a basic CI pipeline. You can use one of the documented use cases or language guides as a starting point.
- A pre-existing app on Heroku.
- Basic familiarity with Git and SSH.
Connecting CI and deployment pipelines with a promotion#
Start by defining a promotion at the end of your
- name: Deploy to Heroku
This defines a simple deployment pipeline that can be triggered manually for every revision on every branch. You can define as many pipelines as you need for any project, using a variety of options and conditions. For designing custom delivery pipelines, consult the promotions reference documentation.
Heroku deployment via HTTP authentication#
In this example, we're going to configure Heroku deployment using HTTP Git transport.
Creating and Storing an API token#
The Heroku HTTP Git endpoint only accepts API-key based HTTP Basic authentication. For that, Heroku stores API tokens in the standard Unix file
$HOME\_netrc on Windows), so that other tools such as Git can access the Heroku API with little or no extra work.
Therefore, the first step is to locally create the API token which Semaphore will use to access Heroku.
heroku login (or any other heroku command that requires authentication) creates or updates your
$ heroku login
heroku: Press any key to open up the browser to login or q to exit
› Warning: If browser does not open, visit
heroku: Waiting for login...
Logging in... done
Logged in as firstname.lastname@example.org
$ cat ~/.netrc
Injecting an API token#
Next, we need to make the
.netrc file available to Semaphore. Use the sem create secret command to inject the file.
sem create secret heroku-http -f ~/.netrc:~/.netrc
You can verify the existence of your new secret with the command shown below:
$ sem get secrets
Defining the Deployment pipelines#
Finally, let's define what happens in our
name: Heroku deployment
- name: Deploy
- name: heroku-http
- name: HEROKU_APP_NAME
- name: Push code
- checkout --use-cache
- heroku git:remote -a $HEROKU_APP_NAME
- git push heroku -f $SEMAPHORE_GIT_BRANCH:master
Note: change the value of
HEROKU_APP_NAME to match your application's
details as registered on Heroku.
Note: For deploying to Heroku, you must use
--use-cache option in order to avoid a shallow clone of your GitHub
Verifying that it works#
Push a new commit on any branch and open Semaphore to watch the new workflow run. If all goes well, you'll see the "Promote" button next to your initial pipeline. Click on it to launch deployment, and open the "Push code" job to observe its' output.
Authentication method Expired#
.netrc file is not a permanent token. It must be updated from time to time.
If you encounter a job hanging at the authentication step, it could be due to an expired
.netrc file. In this case, recreating the file and the secret should solve the issue.
Congratulations! You have automated deployment of your application to Heroku. Here’s some recommended reading: