Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 37 ยท Deployment and Releases

Releases and Rollbacks

Understand Heroku releases: what creates one, how to list and inspect them, how rollback really works, what it cannot undo, and how to deploy with a safety net.

Every change to a running Heroku app becomes a release: a numbered, immutable snapshot of the code (a slug) together with the config vars at that moment. Releases give you a history of what changed and, more importantly, a one-command way to go back when a deploy goes wrong.

This lesson explains what creates a release, how to read the history, how a rollback behaves, and the limits you must know before you rely on one.

What creates a release

A new release (with the next version number, v1, v2, v3 and so on) is created whenever:

  • you deploy new code (a successful build),
  • you change config vars (heroku config:set, heroku config:unset),
  • you add, remove or change an add-on (attachments change config vars),
  • you roll back to an earlier release,
  • some platform actions update the app's state.

Releases are never edited. A mistake is repaired by creating a newer release, not by rewriting an old one. The latest successful release is the one your dynos run.

Reading the history

CONSOLE
$ heroku releases
$ heroku releases -n 5
$ heroku releases:info v12
$ heroku releases:output v12
  • heroku releases lists versions, descriptions (such as "Deploy 9f3c1d2", "Set FEATURE_X config vars", "Rollback to v7"), who did it and when.
  • releases:info shows details for one version, including its slug and the config vars it carried.
  • releases:output shows the output of the release phase command for that release, if you defined one (see release phase and migrations).

Add --json to any of these for scripting. The history is a rich debugging tool: "the errors started around 14:05" plus "v31 was deployed at 14:03" is often the whole investigation.

Rolling back

CONSOLE
$ heroku releases
$ heroku rollback v30

heroku rollback with no argument returns to the previous release; with a version it returns to that one. Two behaviors surprise newcomers:

  1. A rollback creates a new release. If you are on v33 and roll back to v30, you get v34, whose slug and config vars equal v30's. History only moves forward, so you can always see what happened.
  2. A rollback restores code and config vars, nothing else. It does not undo database changes, add-on plan changes, or data your app already wrote. If v33 ran a migration that dropped a column, going back to v30's code does not bring the column back.

Because of that second point, the safest deploys are backward compatible: new code that works with both the old and the new database schema, deployed in two steps (add the column first, remove the old one in a later release). With that discipline a rollback is boring, as it should be.

flowchart LR
  V1["v30<br/>good"] --> V2["v31"] --> V3["v32"] --> V4["v33<br/>bad deploy"]
  V4 -->|"heroku rollback v30"| V5["v34<br/>copy of v30"]

A rollback adds a new release that reuses an older slug and its config.

Stand-in: a release ledger

The stand-in below keeps an append-only list of releases, supports config changes and rollbacks, and shows that history never shrinks. The version numbers and descriptions follow the platform's conventions, but this is an invented model.

Python Stand-in: releases and rollback

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.

Look at v5: its slug matches v2 but it is a brand-new version, and FEATURE_X is whatever v2 had (not set yet).

Stand-in: diff two releases

When you are not sure what changed between a working and a broken release, compare their config vars. This stand-in prints added, removed and changed keys.

Python Stand-in: diff the config of two releases

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.

In the real CLI you get this information with heroku releases:info v30 and heroku releases:info v33, then compare by eye or with a diff tool.

Safer deployment habits

  • Deploy to staging first and promote with a pipeline.
  • Ship small changes so the culprit is obvious.
  • Make schema changes backward compatible (expand, deploy, then contract).
  • Use release phase to run migrations before new code starts, and a failing migration cancels the release automatically.
  • Know the rollback target before you deploy: note the current version number.
  • Watch the logs for two minutes after each deploy.
  • Prefer a feature flag for risky behavior: turning it off is a config var change, which is also a (fast) release.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which of these creates a new release?

    Config changes create a release with the existing slug and updated config. Reading commands do not.
  2. 2. You are on v33 and run heroku rollback v30. What version are you on afterward?

    Rollbacks create a new release that copies v30's slug and config, so the version number increases.
  3. 3. What does a rollback not undo?

    Only code and config vars are restored. Data and schema changes in add-ons stay as they are.
  4. 4. Which design makes rollbacks safest?

    If new and old code both work with the current schema, going back is harmless.

Summary

  • Every deploy, config change and add-on change creates an immutable, numbered release.
  • heroku releases and releases:info show the history; heroku rollback creates a new release from an older one.
  • Rollback restores code and config only, never database data or schema.
  • Use backward-compatible changes, small deploys and staging to keep rollbacks boring.

Next: Release phase and migrations