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.
Set Up Pipelines
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
Defining a Workflow
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 myapp-staging:
$ 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-staging and myapp-production. Add the production app as the downstream environment:
$ heroku pipeline:add -a myapp-staging myapp-production
Confirm by calling heroku pipeline:
$ heroku pipeline -a myapp-staging
Pipeline: myapp-staging ---> myapp-production
Diff Between Application Environments
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)
Promote Changes
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.
Feedback?
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 labs@heroku.com.