Deploy to Heroku
In this how-to guide, you will learn how to configure CircleCI to deploy to Heroku.
Introduction
Heroku is a popular platform for hosting applications in the cloud. To configure CircleCI to deploy your application to Heroku, follow the steps below.
Deploy with the Heroku orb
1. Create an account
Create a Heroku account and follow the Getting Started on Heroku documentation to set up a project in your chosen language.
2. Create environment variables
Add the name of your Heroku application and your Heroku API key as environment variables as HEROKU_APP_NAME
and HEROKU_API_KEY
, respectively. To take advantage of secrets masking, it is best practice to set environment variables at the project level or within a context.
3. Deploy with the Heroku orb
Use the Heroku orb to keep your configuration simple. The deploy-via-git
installs the Heroku CLI in the primary container, runs any pre deployment steps you define, deploys your application, then runs any post-deployment steps you define. See the Heroku orb page in the orbs registry for full details of parameters and options:
Make sure to replace any placeholder versions in the example.
version: 2.1
orbs:
heroku: circleci/heroku@x.y
workflows:
heroku_deploy:
jobs:
- heroku/deploy-via-git:
post-steps:
- run: your-database-migration-command #example of a post-deployment step
pre-steps:
- run: command-that-run-before-deploying #example of a pre-deployment step
For more detailed information about these Heroku orbs, refer to the CircleCI Heroku Orb.
Heroku deployment with 2.0 configuration
1. Create an account
Create a Heroku account and follow the Getting Started on Heroku documentation to set up a project in your chosen language.
2. Create environment variables
Add the name of your Heroku application and your Heroku API key as environment variables as HEROKU_APP_NAME
and HEROKU_API_KEY
, respectively. To take advantage of secrets masking, it is best practice to set environment variables at the project level or within a context.
3. Create deploy job
In your .circleci/config.yml
, create a deploy
job and add an executor type.
4. Add steps to your deploy job
Add steps
to your deploy
job to checkout and deploy your code. You can specify which branch you would like to deploy. The example below specifies the main branch, and deploys using a git push
command.
version: 2.1
jobs:
build:
docker:
- image: <docker-image-name-tag>
steps:
- checkout
# build job ommitted for brevity
deploy:
docker:
- image: <docker-image-name-tag>
steps:
- checkout
- run:
name: Deploy Main to Heroku
command: |
git push https://heroku:$HEROKU_API_KEY@git.heroku.com/$HEROKU_APP_NAME.git main
workflows:
build-deploy:
jobs:
- build
- deploy:
requires:
- build # only run deploy-via-git job if the build job has completed
filters:
branches:
only: main # only run deploy-via-git job on main branch
Heroku provides the option "Wait for CI to pass before deploy" under deploy / automatic deploys. See the Heroku documentation for details. |
Help make this document better
This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.
- Suggest an edit to this page (please read the contributing guide first).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
Need support?
Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.
You can also visit our support site to find support articles, community forums, and training resources.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.