Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 37 ยท CI, Pipelines and Review Apps

Pipelines and Promotion

Group Heroku apps into a pipeline with review, development, staging and production stages, connect GitHub, auto-deploy branches and promote the same slug between stages.

A real product needs more than one copy of the app: a place to try changes, a staging copy that mirrors production, and production itself. Heroku calls a group of apps that form such a path a pipeline. This lesson shows the stages, the commands, and the key idea that makes pipelines safe: you promote the exact build that was tested, you do not build again.

The Heroku CLI and dashboard cannot run on this site, so commands are read-only text and the promotion model is a runnable stand-in.

Stages

Each app in a pipeline sits in one stage:

  1. Review: temporary apps, one per pull request (review apps).
  2. Development: an app that follows a main or dev branch, for early checks.
  3. Staging: a production-like app for final testing.
  4. Production: the app real users reach.
flowchart LR
    PR["Pull request"] --> RV["Review app"]
    RV -->|"merge"| DEV["Development"]
    DEV -->|"promote"| STG["Staging"]
    STG -->|"promote"| PRD["Production"]

Code flows from left to right; each promotion moves an already-built release.

Creating a pipeline

Terminal
heroku pipelines:create my-pipeline --app my-app-staging --stage staging
heroku pipelines:add my-pipeline --app my-app-prod --stage production
heroku pipelines:info my-pipeline
heroku pipelines:connect my-pipeline --repo yourname/my-repo

pipelines:create makes the pipeline and puts the first app into a stage. pipelines:add puts more apps in. pipelines:connect links a GitHub repository so Heroku can deploy branches and open review apps. You can do all of this in the dashboard under Pipelines, where the stages appear as columns.

GitHub integration and auto deploys

With a connected repo, each app in the pipeline can have automatic deploys from a branch: for example main goes to staging whenever it changes. You can ask Heroku to wait for CI to pass before deploying, so a red test run never ships. Production is usually not auto-deployed; people promote it on purpose.

Promotion

Terminal
heroku pipelines:promote --app my-app-staging --to my-app-prod

Promotion copies the slug (the compiled build: your code, dependencies and runtime) from the source app to the target apps and creates a new release. The target keeps its own config vars and add-ons. Why this matters:

  • What you tested on staging is byte for byte what runs in production; there is no second build that could pick up a different dependency.
  • Differences between environments belong in config vars (DATABASE_URL, API keys, feature flags), never in code.
  • Rolling back is easy (troubleshooting).
Python Stand-in: promote the same slug

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Both apps run the same slug but keep different config values (sandbox against live). That is the promise of pipelines.

Release phase and promotion

A release process in your Procfile (for example a migration command) runs on every release, including promotions. So a migration tested on staging runs again on production's database when you promote. Keep migrations safe to run once per environment and make them backward compatible, so a rollback of the code does not need a rollback of the schema.

Working agreements for a team

  • Merge to main only through pull requests with passing checks (Heroku CI).
  • Staging gets every merge; production gets deliberate promotions, ideally after a quick smoke test.
  • Use the same add-on types in staging as production (Postgres version, Redis) so that bugs appear before users see them.
  • Record who promoted and when; the dashboard's activity feed and heroku releases keep that history.
  • Use pipeline couplings sparingly: each app belongs to only one pipeline.
Python Stand-in: a promotion gate

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Heroku does not enforce such a gate by itself in the pipeline UI; teams build it with CI status checks, branch protection and team roles (security and access).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does promotion copy from staging to production?

    Promotion reuses the slug, so what was tested is exactly what runs; config vars and add-ons stay separate per app.
  2. 2. Which stage holds one temporary app per pull request?

    Review apps are created for pull requests and removed when they are closed.
  3. 3. Where should differences between staging and production live?

    Environment differences belong in config vars so the same slug works in every stage.
  4. 4. Why is production often not auto-deployed?

    A manual promotion step gives a chance to verify staging first.

Summary

  • A pipeline groups apps in review, development, staging and production stages.
  • Connect GitHub for auto deploys and review apps; wait for CI before deploying.
  • Promote slugs instead of rebuilding; config vars carry per-environment differences.
  • Release-phase commands run on promotion, so keep migrations backward compatible.

Next: Heroku CI: Test Runs