cc by-sa flurdy

Staging environments and pipeline promotion with Heroku

How to create staging and production environments for you Heroku applications. Then use Heroku's pipeline feature to promote releases through these environments

Sign up & install

If you have not already signed up with Heroku and installed the Heroku Toolbelt, follow my Heroku tips's sign up and install sections.


Kill Bill

You will off course need an application to promote and deploy. There is a whole set of technology stacks that Heroku supports. For an example you can read my Play 2.0 + Scala + Heroku howto.


Your application and company may require several development and staging environments. For this example we will use a development, a staging and a production environment.

Lets create a development environment application:

heroku create myapp-dev --remote dev --region eu;

Replace myapp with your unique application name. Valid regions are EU and US. US is default so then the whole parameter can be omitted.

You can now add add-ons and configure environment properties, as detailed in Heroku tips.

Development deploy

When you application is ready to start testing you can deploy it to the development environment with git.

git push dev master ;
heroku open --remote dev && heroku logs -t --remote dev


When the development environment is configured well enough you can copy it as a template for the other environments using Heroku's fork feature.

Create a staging environment.

heroku fork -a myname-dev myname-staging --region us

Forking does not automatically add it as a remote to your local git repository.

heroku info -a myname-staging

Copy the "[email protected]:myapp-staging.git" url and add it as a remote.

git remote add staging [email protected]:myapp-staging.git

And a production environment.

heroku fork -a myname-dev myname-live ;
git remote add live [email protected]:myapp-live.git

There will be some customisation for each environment afterwards, but the forking copies across the most useful features including add-ons.


Whilst still in beta mode the pipeline feature by Heroku is really useful to stream line the release process. It allows you to specify which application(environment) your application can be promoted to once that environment have been signed off.

Configure the pipelining with enabling the feature.

heroku labs:enable pipelines

Then install pipeline into your local Heroku toolbelt.

heroku plugins:install git://

And set the promotion target for the development environment to be staging.

heroku pipeline:add myapp-staging --remote dev

And for staging the pipeline environment is production.

heroku pipeline:add myapp-live --remote staging

You can then verify the pipeline.

heroku pipeline --remote dev;
heroku pipeline --remote staging;
heroku pipeline --remote live

Release process with promotion

Now we have an application to deploy, 3 environments to stage via and a pipeline feature to assist with promotion.

You have deployed your initial version via git to the development environment. If you want to see if different versions are on development and staging, there is a diff feature.

heroku pipeline:diff --remote dev

Note, you will need to have an initial version on the environment for this to make sense.

If you want to promote this to the staging environment, simply promote it.

heroku pipeline:promote --remote dev ;
heroku open --remote staging && heroku logs -t --remote staging

If you want to release this to production.

heroku pipeline:promote --remote staging ;
heroku open --remote live && heroku logs -t --remote live


If you want a log of when releases where promoted there is a release log per environment

heroku releases --remote live


If a bad release has been rolled out your can easily rollback to the previous release entry.

heroku rollback --remote live

One binary

One thing missing from the general Heroku's git push workflow is the lack of one binary for all environments. Experience has taught us that different binaries in different environments may introduce unexpected bugs.

With pipeline promotion of builds you are mimicking the one binary pattern.

Heroku have also announced some Enterprise support for continuous integration tools that have build pack plugins to assist with building one binary (slugs) before any deployment to Heroku. Some of this support is included with the new Platform API.

Other add-on providers also supply binary promotion, such as Codeship.

Feedback & Contact

For typos and minor change suggestions, please clone this document repository at:, and send a pull request.

To hire me as a consultant / contractor contact me via

Or contact me via