1. Resources
  2. /
  3. Plugins
  4. /
  5. heroku-container-deploy-buildkite-plugin

Heroku Container Deploy

Deploy pre-built docker images, typically with docker-compose-buildkite-plugin, to using the Heroku Container Registry. It follows the official recommended steps for Docker deploys on Heroku. See ecr-buildkite-plugin for authenticating with AWS ECR.

Design Decision

Heroku API is favoured over depending on the Heroku CLI. This helps to avoid problems with transitive npm dependencies causing CI blockage at scale.

Example

Deploy a pre-built images from ECR to heroku container registry.

steps:
  - label: ":heroku: Deploy my-app app (web)"
    plugins:
      - envato/heroku-container-deploy#v1.3.0:
          app: my-app
          process-type-images:
            - web:XXXXXXXXXXXX.dkr.ecr.us-east-1.amazonaws.com/my-repo:heroku-web-${BUILDKITE_COMMIT}

Deploy multiple pre-built images from ECR to heroku container registry.

steps:
  - label: ":heroku: Deploy my-app app (web and worker)"
    plugins:
      - envato/heroku-container-deploy#v1.3.0:
          app: my-app
          process-type-images:
            - web:XXXXXXXXXXXX.dkr.ecr.us-east-1.amazonaws.com/my-repo:heroku-web-${BUILDKITE_COMMIT}
            - worker:XXXXXXXXXXXX.dkr.ecr.us-east-1.amazonaws.com/my-repo:heroku-worker-${BUILDKITE_COMMIT}

Deploy multiple pre-built images including a Release Phase from ECR to heroku container registry. Plugin will stream the release output to Buildkite logs.

steps:
  - label: ":heroku: Deploy my-app app (web, worker and release)"
    plugins:
      - envato/heroku-container-deploy#v1.3.0:
          app: my-app
          process-type-images:
            - web:XXXXXXXXXXXX.dkr.ecr.us-east-1.amazonaws.com/my-repo:heroku-web-${BUILDKITE_COMMIT}
            - worker:XXXXXXXXXXXX.dkr.ecr.us-east-1.amazonaws.com/my-repo:heroku-worker-${BUILDKITE_COMMIT}
            - release:XXXXXXXXXXXX.dkr.ecr.us-east-1.amazonaws.com/my-repo:heroku-release-${BUILDKITE_COMMIT}

Configuration

app (Required, string)

Heroku app name

key-name (Optional, string)

The name of the environment variable that contains the Heroku API key. Defaults to HEROKU_API_KEY

process-type-images (Required, Array of string)

List of process types and their image repository to deploy.

<proc-type>:<ecr>:<tag>

releasing (Optional, Array of string)

List of process type names to be released. It will allays pull, tag and push all images, but it will only patch the Heroku Formation API with these images.

Default: All process types in process-type-images except one named migrations

Developing

Testing

docker-compose run --rm tests

Linting

docker-compose run --rm lint

The plugins listed on this webpage are provided for informational purposes only. They have not undergone any formal security review or assessment. While we strive to provide useful resources, we cannot guarantee the safety, reliability, or integrity of these plugins. Users are strongly advised to conduct their own security evaluations before downloading, installing, or using any plugin. By using these plugins, you acknowledge and accept any risks associated with their use. We disclaim any liability for any harm or damages arising from the use of the plugins listed.

Start turning complexity into an advantage

Create an account to get started with a 30-day free trial. No credit card required.

Buildkite Pipelines

Platform

  1. Pipelines
  2. Pipeline templates
  3. Public pipelines
  4. Test Engine
  5. Package Registries
  6. Mobile Delivery Cloud
  7. Pricing

Hosting options

  1. Self-hosted agents
  2. Mac hosted agents
  3. Linux hosted agents

Resources

  1. Docs
  2. Blog
  3. Changelog
  4. Webinars
  5. Plugins
  6. Case studies
  7. Events
  8. Migration Services
  9. Comparisons

Company

  1. About
  2. Careers
  3. Press
  4. Brand assets
  5. Contact

Solutions

  1. Replace Jenkins
  2. Workflows for AI/ML
  3. Testing at scale
  4. Monorepo mojo
  5. Bazel orchestration

Legal

  1. Terms of Service
  2. Acceptable Use Policy
  3. Privacy Policy
  4. Subprocessors
  5. Service Level Agreement

Support

  1. System status
  2. Forum
© Buildkite Pty Ltd 2025