Last updated November 21, 2023

Heroku Pipelines let developers specify a collection of Heroku apps to represent the different deployment stages of a single codebase. Every app in a pipeline represents one of the following deployment stages:

• Development
• Review
• Staging
• Production

As an add-on partner, you can access some of an app’s pipeline information with the Platform API for Partners. Common use cases for this information include the following:

• When you create a unified dashboard for your customers, you can visually group content that corresponds to different apps in the same pipeline.

• You can track developer pipeline details in your add-on’s metrics to better understand how developers are using your add-on.

Prerequisites

Inspecting pipeline information requires access to the Platform API for Partners. If your add-on doesn’t already use it, see Platform API for Partners to get started.

Additionally, if you want to use this information during provisioning, you should take advantage of Asynchronous Provisioning. Otherwise you run the risk of hitting the 30 second timeout from the original request.

Get the provisioning app’s id

To obtain an app’s pipeline details, you must first obtain the id of the app that provisioned your add-on.

When a developer provisions your add-on, your add-on receives a POST request at /heroku/resources with a JSON body like the following:

{
  "heroku_id": "app1234@heroku.com",
  "plan": "basic",
  "region": "amazon-web-services::us-east-1",
  "callback_url": "https://api.heroku.com/vendor/apps/app1234@heroku.com",
  "options": {},
  "uuid": "01234567-89ab-cdef-0123-456789abcdef"
}

Provide the value of the included uuid field in a GET request to the Add-on Info endpoint:

GET /addons/{resource-uuid}

Content-Type: application/json
Accept: application/vnd.heroku+json; version=3
Authorization: Bearer {access-token}

The endpoint responds with a JSON body like the following:

{
  "actions": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "label": "Example",
    "action": "example",
    "url": "http://example.com?resource_id=:resource_id",
    "requires_owner": true
  },
  "addon_service": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-postgresql"
  },
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "config_vars": [
    "FOO",
    "BAZ"
  ],
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "acme-inc-primary-database",
  "plan": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-postgresql:dev"
  },
  "provider_id": "abcd1234",
  "state": "provisioned",
  "updated_at": "2012-01-01T12:00:00Z",
  "web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}

The app object in the response body includes the unique id of the app that provisioned your add-on. You can use this id to look up the app’s associated pipeline details.

Getting most pipeline details

Now that you have the primary app’s id, provide it in a request to the Pipeline Coupling Info endpoint to obtain the id of its associated pipeline:

GET /apps/{app-id}/pipeline-couplings

Content-Type: application/json
Accept: application/vnd.heroku+json; version=3
Authorization: Bearer {token}

The endpoint responds with a JSON body like the following:

[
  {
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "pipeline": {
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "stage": "production",
    "updated_at": "2012-01-01T12:00:00Z"
  }
]

The id field of the returned pipeline object uniquely identifies the pipeline. The stage field indicates which deployment stage this app corresponds to.

This endpoint returns an array for consistency with other endpoints, but an app can be a member of only one pipeline (so the array contains at most one item).

Getting a pipeline’s name

You can look up a pipeline’s name with the id you obtained in the previous step:

GET /pipelines/{pipeline-uuid}

Content-Type: application/json
Accept: application/vnd.heroku+json; version=3
Authorization: Bearer {token}

{
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "example",
  "updated_at": "2012-01-01T12:00:00Z"
}

Summary

Gathering pipeline and stage information for apps associated with resources provides opportunities to improve user experiences for customers and improve metrics for partners. Please open a support ticket with any questions or comments.