> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# circleci/heroku

Easily install and use the Heroku CLI with CircleCI to build, test, and deploy your applications to Heroku.


## Commands

### check-authentication

Verifies the Heroku API key has been added so we can authenticate.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `print-whoami` | boolean | false | Print the result of heroku auth:whoami. |

### create-review

Deploys a new review app. Artifacts for creating the review should be saved in a prior step.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `artifact-pattern` | string |  | RegEx or filename of artifact to deploy to Heroku. |
| `circleci-api-key` | env_var_name | CIRCLE_TOKEN | Environment variable containing the Heroku API key |
| `heroku-api-key` | env_var_name | HEROKU_API_KEY | The name of the environment variable containing your Heroku API Key. |
| `pipeline` | string |  | Heroku pipeline to deploy with (UUID). |

### deploy-via-git

Use Git to push the changes of the current tag or branch to Heroku for deployment.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `api-key` | env_var_name | HEROKU_API_KEY | The name of the environment variable containing your Heroku API Key. |
| `app-name` | string | $HEROKU_APP_NAME | The name of your Heroku app. May also refer to an environment variable. |
| `branch` | string | $CIRCLE_BRANCH | Deploy the given branch. The default value is your current branch. Accepts strings which may contain an environment variable. |
| `force` | boolean | false | Whether or not to force the git push (i.e. `git push -f`). Defaults to false. |
| `maintenance-mode` | boolean | false | Use this to automatically enable maintenance mode before pre-deploy steps and have it disabled after post-deploy steps have been run. |
| `no_output_timeout` | string | 10m | Allows you to specify the no_output_timeout for the `git push` to heroku. Defaults to 10m. |
| `tag` | string | $CIRCLE_TAG | Deploy the given tag. The default value is your current tag. |

### install

Download and install the Heroku CLI. Will be skipped if the CLI is already installed in the system.


### push-docker-image

Push a Docker image to the Heroku Docker registry.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `api-key` | env_var_name | HEROKU_API_KEY | The name of the environment variable containing your Heroku API Key. |
| `app-name` | string | $HEROKU_APP_NAME | The name of your Heroku app. May also refer to an environment variable. |
| `no_output_timeout` | string | 10m | Allows you to specify the no_output_timeout for the `git push` to heroku. Defaults to 10m. |
| `process-types` | string |  | Process types. |
| `recursive` | boolean | false | Push all Dockerfiles in the directory to Heroku. |

### release-docker-image

Release a Docker image from the Heroku Docker registry.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `api-key` | env_var_name | HEROKU_API_KEY | The name of the environment variable containing your Heroku API Key. |
| `app-name` | string | $HEROKU_APP_NAME | The name of your Heroku app. May also refer to an environment variable. |
| `no_output_timeout` | string | 10m | Allows you to specify the no_output_timeout for the `git push` to heroku. Defaults to 10m. |
| `process-types` | string | web | Process types. |

## Jobs

### deploy-via-git

Use Git to push the changes of the current tag or branch to Heroku for deployment.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `api-key` | env_var_name | HEROKU_API_KEY | The name of the environment variable containing your Heroku API Key. |
| `app-name` | string | HEROKU_APP_NAME | Add the name of your application to an environment variable with this name. |
| `branch` | string | $CIRCLE_BRANCH | Deploy the given branch. The default value is your current branch. Accepts strings which may contain an environment variable. |
| `force` | boolean | false | Whether or not to force the git push (i.e. `git push -f`). Defaults to false. |
| `maintenance-mode` | boolean | false | Use this to automatically enable maintenance mode before pre-deploy steps and have it disabled after post-deploy steps have been run. |
| `no_output_timeout` | string | 10m | Allows you to specify the no_output_timeout for the `git push` to heroku. Defaults to 10m. |
| `post-deploy` | steps |  | A list of post-deploy steps that are run after deployment. This would be an ideal place to scale any processes back up. |
| `pre-deploy` | steps |  | A list of pre-deploy steps that are run before deployment. This would be an ideal place to scale any processes down. |
| `tag` | string | $CIRCLE_TAG | Deploy the given tag. The default value is your current tag. |

### push-docker-image

Quickly and easily take the changes to this branch and deploy them to Heroku automatically with this job.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `app-name` | string | $HEROKU_APP_NAME | The name of your Heroku App. For backwards compatibility the literal value `$HEROKU_APP_NAME` is the default, so you can easily use this command by setting an environment variable called HEROKU_APP_NAME |
| `maintenance-mode` | boolean | false | Use this to automatically enable maintenance mode before pre-deploy steps and have it disabled after post-deploy steps have been run. |
| `post-deploy` | steps |  | A list of post-deploy steps that are run after deployment. This would be an ideal place to scale any processes back up. |
| `pre-deploy` | steps |  | A list of pre-deploy steps that are run before deployment. This would be an ideal place to scale any processes down. |

## Executors

### default

A highly efficient and cached Ubuntu-based image. Consider using this executor or selecting an image for your language https://hub.docker.com/r/cimg/


| Parameter | Type | Default | Description |
|---|---|---|---|
| `tag` | string | current | Pick a specific cimg/base tag: https://hub.docker.com/r/cimg/base/tags
 |

## Examples

### create_review_app

A sample job that deploys a review app to Heroku, that does not run on the main "deployed" branch. Assumes that your CircleCI token is stored in $CIRCLECI_API_KEY and Heroku's API key under $HEROKU_API_KEY.


```yaml
version: '2.1'
orbs:
  heroku: circleci/heroku@2.0
jobs:
  create-review-app:
    executor: heroku/default
    steps:
      - checkout
      - run:
          command: tar -czvf my-project.tar.gz ~/project
          name: Bundle our project project
          working_directory: ~/
      - store_artifacts:
          path: ~/my-project.tar.gz
      - heroku/create-review:
          artifact-pattern: '*.tar.gz'
          pipeline: PIPELINE-UUID
workflows:
  heroku_review:
    jobs:
      - create-review-app:
          filters:
            branches:
              ignore: main
```

### use_heroku_commands

'A simple example of a job utilizing the `install` and `deploy-via-git` commands.'


```yaml
version: '2.1'
orbs:
  heroku: circleci/heroku@2.0
jobs:
  deploy:
    executor: heroku/default
    steps:
      - checkout
      - heroku/install
      - run:
          command: >
            echo "The command above installs Heroku, the command below deploys.
            What you do inbetween is up to you!"
      - heroku/deploy-via-git
workflows:
  heroku_deploy:
    jobs:
      - deploy
```

### use_heroku_job

Easily deploy to Heroku with a single job supplied by this orb.


```yaml
version: '2.1'
orbs:
  heroku: circleci/heroku@2.0
workflows:
  heroku_deploy:
    jobs:
      - heroku/deploy-via-git:
          post-steps:
            - run: your-database-migration-command
          pre-steps:
            - run: command-that-run-before-deploying
```