---
title: "Deploy to Heroku"
description: "Configure CircleCI to deploy your application to Heroku, either with the Heroku orb or with a custom deploy job and environment variables."
platform: "Cloud, Server"
doc_version: "Server"
last_updated: "2026-10-15"
---

> For current CircleCI product defaults, deprecated patterns, and Cloud/Server differences, see [AGENTS.md](https://circleci.com/docs/AGENTS.md).
>
> For the complete documentation index and site structure, see [llms.txt](https://circleci.com/docs/llms.txt).

# Deploy to Heroku

In this how-to guide, you will learn how to configure CircleCI to deploy to Heroku.

## Introduction

[Heroku](https://www.heroku.com/) is a popular platform for hosting applications in the cloud. To configure CircleCI to deploy your application to Heroku, follow the steps below.

## Using the Heroku orb

### 1\. Create an account

Create a Heroku account and follow the [Getting Started on Heroku](https://devcenter.heroku.com/start) 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](https://circleci.com/docs/guides/security/contexts/#secrets-masking), it is best practice to set environment variables at the [Project Level](https://circleci.com/docs/guides/security/set-environment-variable/#set-an-environment-variable-in-a-project) or within a [Context](https://circleci.com/docs/guides/security/set-environment-variable/#set-an-environment-variable-in-a-context).

### 3\. Deploy with the Heroku orb

Use the [Heroku orb](https://circleci.com/developer/orbs/orb/circleci/heroku) to keep your configuration simple. The `deploy-via-git` job 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](https://circleci.com/developer/orbs/orb/circleci/heroku) for full details of parameters and options:

Make sure to replace any placeholder versions in the example.

```yaml
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](https://circleci.com/developer/orbs/orb/circleci/heroku).

## Deploy without the Heroku orb

### 1\. Create an account

Create a Heroku account and follow the [Getting Started on Heroku](https://devcenter.heroku.com/start) 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](https://circleci.com/docs/guides/security/contexts/#secrets-masking), it is best practice to set environment variables at the [Project Level](https://circleci.com/docs/guides/security/set-environment-variable/#set-an-environment-variable-in-a-project) or within a [Context](https://circleci.com/docs/guides/security/set-environment-variable/#set-an-environment-variable-in-a-context).

### 3\. Create deploy job

In your `.circleci/config.yml`, create a `deploy` job and add an [Executor Type](https://circleci.com/docs/guides/server/execute/executor-intro/).

### 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.

```yaml
version: 2.1

jobs:
  build:
    docker:
      - image: <docker-image-name-tag>
    steps:
      - checkout
      # Additional steps omitted 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 the deploy job once the build job has completed
          filters: pipeline.git.branch == "main" # only run the deploy job on the main branch
```

Heroku provides the option "Wait for CI to pass before deploy" under deploy / automatic deploys. See the [Heroku documentation](https://devcenter.heroku.com/articles/github-integration#automatic-deploys) for details.