Editor's Note: The version of Pipelines described in this blog post has been deprecated and replaced by a new non-labs implementation. Features added through Heroku Labs are experimental and may change or be removed without notice.
heroku fork lets you create unique, running instances of existing applications in a single command, making it fast and simple to set up homogenous development, staging and production environments. But have you ever wished you could deploy directly from staging to a production app after testing and validation?
Heroku pipelines, now an experimental feature available in Heroku Labs, lets you define the relationship between apps and easily promote a slug from one app to another. On Heroku, a slug is a bundle of your source, fetched dependencies, the language runtime, and compiled/generated output of the build system, ready for execution.
Pipelines will copy the slug from the upstream app to the downstream app. Time to deploy is significantly faster as the slug is already compiled - pipelines simply copies and moves it to the downstream app. Pipelines also reduces the risk of accidentally pushing the wrong commit or deploying to the wrong environment, and makes it easier to manage your workflow so you can develop and test new features quickly, verify expected behavior, and release safely to end users. Here’s how to try it.
To use pipelines, you must first enable it in Heroku Labs:
$ heroku labs:enable pipelines
Then install the CLI plugin:
$ heroku plugins:install git://github.com/heroku/heroku-pipeline.git
If you don’t already have your application environments set up, use
heroku fork to quickly spin up unique, homogeneous application environments from existing apps. You can then use these instances for various stages of your workflow.
For this example, let’s assume that
myapp-production is the name of your existing app, and you want to create a fork called
$ heroku fork -a myapp-production myapp-staging
This will clone the source app’s precompiled slug and config-vars, re-provision the source app’s add-ons, copy over Heroku Postgres data (if present), and scale web processes to one dyno in the new
myapp-staging environment. For more on
heroku fork, its behaviors and limitations, read the blog post.
Next, we use pipeline to map the relationship between the staging and production apps. In pipeline vocabulary, a production app is "downstream" from a staging app. Given a dev ---> staging ---> production pipeline, staging would be downstream of dev, and production downstream of staging.
For simplicity’s sake, let’s set up a basic staging-to-production workflow between
myapp-production. Add the production app as the downstream environment:
$ heroku pipeline:add -a myapp-staging myapp-production
Confirm by calling
$ heroku pipeline -a myapp-staging Pipeline: myapp-staging ---> myapp-production
Diff is a powerful tool for seeing changes between code, here extended to entire application environments. Diff against your downstream app:
$ heroku pipeline:diff Comparing myapp-staging to myapp-production ...done, myapp-staging ahead by 1 commit: 73ab415 2013-07-07 A super important fix (Shanley)
Once you’ve defined a pipeline, you can deploy from one app to a downstream app with one command:
$ heroku pipeline:promote Promoting myapp-staging to myapp-production...done, v2
This will copy the upstream app’s currently running slug to the downstream app as a new release. In this example, application changes made in staging will now be live and running in your production app, ready to serve end users.
Pipelines only manage the application slug. Config vars, Add-ons and other environmental dependencies are not considered part of a pipeline and must be managed independently. Similarly, pipeline doesn't update the downstream app's repository, so a
heroku git:clone of a downstream app will not retrieve the latest code base.
If you're adding application code that interacts with an Add-on, but that Add-on is not yet present in a downstream app, you'll want to provision the Add-on there before promoting application changes to it. Promoted changes by mistake, or need to roll back? Revert a promotion on the downstream app with
heroku rollback to deploy a previous, known version of your code.
Heroku Labs lets us get experimental features out early and often so you can try them and tell us what you like and how we can improve. Check out our current Labs features, and email us at email@example.com.