Pipelines Using the Platform API
Last updated 15 February 2016
Table of Contents
This article describes how to use the pipeline related resources of the Platform API to manage the lifecycle of multiple apps from their development, to staging and to production stages.
Creating a pipeline
To create a pipeline, call the POST /pipelines endpoint with the name of your pipeline. Let’s do so using cURL:
$ curl -X POST -H "Accept: application/vnd.heroku+json; version=3" -n \ -H "Content-Type: application/json" \ -d '{"name": "my-pipeline"}' \ https://api.heroku.com/pipelines
This will generate an empty pipeline with the name my-pipeline and the response will contain the pipeline id which should be used for subsequent API calls.
{
"created_at": "2016-02-11T08:32:08+00:00",
"id": "3be4b9ee-5734-4033-a4c0-28c3d5de99fe",
"name": "my-pipeline",
"updated_at": "2016-02-11T08:32:08+00:00"
}
Adding apps to a pipeline
Now that we’ve constructed the top level pipeline, we can start adding apps to it. To do so, call the POST /pipeline-couplings endpoint, with the name of your app, and the id of the pipeline and which stage the app should belong to.
$ curl -X POST -H "Accept: application/vnd.heroku+json; version=3" -n \ -H "Content-Type: application/json" \ -d '{"app": "my-app-development", "pipeline": "3be4b9ee-5734-4033-a4c0-28c3d5de99fe", "stage": "development"}' \ https://api.heroku.com/pipeline-couplings
This will create a pipeline coupling, which is the association that ties an app to a pipeline.
{
"created_at": "2016-02-11T08:40:42+00:00",
"app": {
"id": "dde884b0-7610-428f-bc36-9393b1c7efb7"
},
"id": "ead76531-1669-4967-9953-e7182605f772",
"pipeline": {
"id": "3be4b9ee-5734-4033-a4c0-28c3d5de99fe",
"name": "my-pipeline"
},
"stage": "development",
"updated_at": "2016-02-11T08:40:42+00:00"
}
An app can only belong to one pipeline at a time.
Inspecting a pipeline
After we’ve added a few apps to the pipeline, we can inspect the contents of it with the GET /pipelines/:id/pipeline-couplings endpoint.
$ curl -H "Accept: application/vnd.heroku+json; version=3" -n \ https://api.heroku.com/pipelines/3be4b9ee-5734-4033-a4c0-28c3d5de99fe/pipeline-couplings
This endpoint will list out all of the pipeline couplings in the pipeline. Each pipeline coupling includes which app and stage they relate to.
[
{
"created_at": "2016-02-11T08:40:42+00:00",
"app": {
"id": "dde884b0-7610-428f-bc36-9393b1c7efb7"
},
"id": "ead76531-1669-4967-9953-e7182605f772",
"pipeline": {
"id": "3be4b9ee-5734-4033-a4c0-28c3d5de99fe",
"name": "my-pipeline"
},
"stage": "development",
"updated_at": "2016-02-11T08:40:42+00:00"
},
{
"created_at": "2016-02-11T08:45:18+00:00",
"app": {
"id": "d4c557ef-8a66-40fa-aa2d-e238fcabcb62"
},
"id": "53e3112b-1d4e-467b-9e67-ec7eab94d019",
"pipeline": {
"id": "3be4b9ee-5734-4033-a4c0-28c3d5de99fe",
"name": "my-pipeline"
},
"stage": "staging",
"updated_at": "2016-02-11T08:45:18+00:00"
},
{
"created_at": "2016-02-11T08:45:36+00:00",
"app": {
"id": "e2296460-0f8c-4430-8d99-1c5ab928f453"
},
"id": "67a22093-bb48-426f-b1c5-3178024279bb",
"pipeline": {
"id": "3be4b9ee-5734-4033-a4c0-28c3d5de99fe",
"name": "my-pipeline"
},
"stage": "production",
"updated_at": "2016-02-11T08:45:36+00:00"
}
]
Finding which pipeline an app belongs to
If our starting point is an app, and we would like to find which pipeline it is a part of, we can use the GET /apps/:id_or_name/pipeline-couplings endpoint.
$ curl -H "Accept: application/vnd.heroku+json; version=3" -n \ https://api.heroku.com/apps/my-app-staging
The response will contain the pipeline coupling tying this app to a pipeline.
{
"created_at": "2016-02-11T08:45:18+00:00",
"app": {
"id": "d4c557ef-8a66-40fa-aa2d-e238fcabcb62"
},
"id": "53e3112b-1d4e-467b-9e67-ec7eab94d019",
"pipeline": {
"id": "3be4b9ee-5734-4033-a4c0-28c3d5de99fe",
"name": "my-pipeline"
},
"stage": "staging",
"updated_at": "2016-02-11T08:45:18+00:00"
}
Finding a pipeline
After we’ve constructed the pipeline, we can list which pipelines we already have using the GET /pipelines endpoint.
$ curl -H "Accept: application/vnd.heroku+json; version=3" -n \ https://api.heroku.com/pipelines
The response will contain all of the pipelines that we have access to.
[
{
"created_at": "2016-02-11T08:32:08+00:00",
"id": "3be4b9ee-5734-4033-a4c0-28c3d5de99fe",
"name": "my-pipeline",
"updated_at": "2016-02-11T08:32:08+00:00"
}
]
In the case that we know the pipeline name, but would like to resolve the name to the pipeline’s id, we can do so with the GET /pipelines/:id_or_name endpoint.
$ curl -H "Accept: application/vnd.heroku+json; version=3" -n \ https://api.heroku.com/pipelines/my-pipeline
If the name resolves to a single pipeline, the response will be the expected pipeline representation. However, if we have access to multiple pipelines with the same name, the call will return a 300 Multiple Choices status and the response a list of the potential candidates.
Performing a promotion
When the pipeline is all set up, and we have changes in the my-app-development app that we would like to downstream to our staging app, we can do so by calling the POST /pipeline-promotions endpoint. The endpoint requires that we pass in the pipeline:id, the app:id of the source app, my-app-development and an array of target app:ids, my-app-staging.
$ curl -X POST -H "Accept: application/vnd.heroku+json; version=3" -n \ -H "Content-Type: application/json" \ -d '{"pipeline":{"id":"3be4b9ee-5734-4033-a4c0-28c3d5de99fe"},"source":{"app":{"id":"dde884b0-7610-428f-bc36-9393b1c7efb7"}},"targets":[{"app":{"id":"d4c557ef-8a66-40fa-aa2d-e238fcabcb62"}}]}' \ https://api.heroku.com/pipeline-promotions
The response from this endpoints contains a status field stating whether the promotion is still in progress, or has been completed.
{
"created_at": "2016-02-11T09:34:05+00:00",
"id": "14990d18-d3f0-44c0-8991-10213a1dc689",
"pipeline": {
"id": "3be4b9ee-5734-4033-a4c0-28c3d5de99fe"
},
"source": {
"app": {
"id": "dde884b0-7610-428f-bc36-9393b1c7efb7"
},
"release": {
"id": "14654174-9f0d-4939-a1a3-188ca134828f"
}
},
"status": "pending",
"updated_at": "2016-02-11T09:34:05+00:00"
}
To obtain an updated version to check for status updates, we can call the GET /pipeline-promotions/:id endpoint.
When the status of the pipeline promotion converges on completed, we can inspect the status of individual targeted apps in the promotion by calling the GET /pipeline-promotions/:id/promotion-targets
$ curl -X POST -H "Accept: application/vnd.heroku+json; version=3" -n \ https://api.heroku.com/pipeline-promotions/14990d18-d3f0-44c0-8991-10213a1dc689/promotion-targets
The response will include the release:id for a successful promotion, and an error_message in the case of a failed promotion.
[
{
"app": {
"id": "d4c557ef-8a66-40fa-aa2d-e238fcabcb62"
},
"error_message": null,
"id": "154e5fa9-578c-4233-8f5f-6b33549c7dd1",
"pipeline_promotion": {
"id": "14990d18-d3f0-44c0-8991-10213a1dc689"
},
"release": {
"id": "53226d94-f915-48ee-bda3-f5b1c8510009"
},
"status": "succeeded"
}
]