Whenever you deploy code, change a config var, or add or remove an add-on resource, Heroku creates a new release and restarts your app. You can list the history of releases, and use rollbacks to revert to prior releases for backing out of bad deploys or config changes.

Setup

Install the releases:basic or releases:advanced add-on for each app you wish to track releases on:

$ heroku addons:add releases:basic
Adding releases:basic to myapp...done.

Release Creation

Release are named in the format vNN, where NN is an incrementing sequence number for each release.

Releases are created whenever you deploy code. In this example, v10 is the release created by the deploy:

$ git push heroku master
...
-----> Compiled slug size is 8.3MB
-----> Launching... done, v10
       http://severe-mountain-793.herokuapp.com deployed to Heroku

Release are created whenever you change config vars. In this example, v11 is the release created by the config change:

$ heroku config:add MYVAR=42
Adding config vars:
  MYVAR => 42
Updating vars and restarting app... done, v11

And releases are created whenever you add, remove, upgrade, or downgrade add-on resources. In this example, v12 is the release created by the add-on change:

$ heroku addons:add memcache
Adding memcache to myapp... done, v12 (free)

Listing Release History

To see the history of releases for an app:

$ heroku releases
Rel   Change                          By                    When
----  ----------------------          ----------            ----------
v52   Config add AWS_S3_KEY           jim@example.com       5 minutes ago            
v51   Deploy de63889                  stephan@example.com   7 minutes ago
v50   Deploy 7c35f77                  stephan@example.com   3 hours ago
v49   Rollback to v46                 joe@example.com       2010-09-12 15:32:17 -0700

To get detailed info on a release:

$ heroku releases:info v24
=== Release v24
Change:      Deploy 575bfa8
By:          jim@example.com
When:        6 hours ago
Addons:      deployhooks:email, releases:advanced
Config:      MY_CONFIG_VAR => 42
             RACK_ENV      => production

Rollback

Use the rollback command to roll back to the last release:

$ heroku rollback
Rolled back to v51

If you are using advanced release mangement, you may choose to specify another release to target:

$ heroku rollback v40
Rolled back to v40

Rolling back will create a new release which is a copy of the state of code and config vars contained in the targeted release. The state of the database or external state held in add-ons (for example, the contents of memcache) will not be affected and are up to you to reconcile with the rollback.

Running on rolled-back code is meant as a temporary fix to a bad deployment. If you are on rolled-back code and your slug is recompiled (for any reason other than a new deployment) your app will be moved back to running on the most recent release. Subscribing to a new add-on or adding/removing a config var will result in your slug being recompiled.

Simple vs Advanced

The simple release management add-on stores two releases: current and previous. This will allow you to roll back only one release - like a single level undo.

The advanced release management add-on stores all releases, allowing you to see the full historical audit trail and roll back to any prior release at any time.