Last updated March 09, 2022

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"
}

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 -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"
  }
]