Skip Navigation
Show nav
Heroku Dev Center
  • Get Started
  • Documentation
  • Changelog
  • Search
  • Get Started
    • Node.js
    • Ruby on Rails
    • Ruby
    • Python
    • Java
    • PHP
    • Go
    • Scala
    • Clojure
  • Documentation
  • Changelog
  • More
    Additional Resources
    • Home
    • Elements
    • Products
    • Pricing
    • Careers
    • Help
    • Status
    • Events
    • Podcasts
    • Compliance Center
    Heroku Blog

    Heroku Blog

    Find out what's new with Heroku on our blog.

    Visit Blog
  • Log inorSign up
View categories

Categories

  • Heroku Architecture
    • Dynos (app containers)
    • Stacks (operating system images)
    • Networking & DNS
    • Platform Policies
    • Platform Principles
  • Command Line
  • Deployment
    • Deploying with Git
    • Deploying with Docker
    • Deployment Integrations
  • Continuous Delivery
    • Continuous Integration
  • Language Support
    • Node.js
    • Ruby
      • Working with Bundler
      • Rails Support
    • Python
      • Background Jobs in Python
      • Working with Django
    • Java
      • Working with Maven
      • Java Database Operations
      • Working with the Play Framework
      • Working with Spring Boot
      • Java Advanced Topics
    • PHP
    • Go
      • Go Dependency Management
    • Scala
    • Clojure
  • Databases & Data Management
    • Heroku Postgres
      • Postgres Basics
      • Postgres Getting Started
      • Postgres Performance
      • Postgres Data Transfer & Preservation
      • Postgres Availability
      • Postgres Special Topics
    • Heroku Data For Redis
    • Apache Kafka on Heroku
    • Other Data Stores
  • Monitoring & Metrics
    • Logging
  • App Performance
  • Add-ons
    • All Add-ons
  • Collaboration
  • Security
    • App Security
    • Identities & Authentication
    • Compliance
  • Heroku Enterprise
    • Private Spaces
      • Infrastructure Networking
    • Enterprise Accounts
    • Enterprise Teams
    • Heroku Connect (Salesforce sync)
      • Heroku Connect Administration
      • Heroku Connect Reference
      • Heroku Connect Troubleshooting
    • Single Sign-on (SSO)
  • Patterns & Best Practices
  • Extending Heroku
    • Platform API
    • App Webhooks
    • Heroku Labs
    • Building Add-ons
      • Add-on Development Tasks
      • Add-on APIs
      • Add-on Guidelines & Requirements
    • Building CLI Plugins
    • Developing Buildpacks
    • Dev Center
  • Accounts & Billing
  • Troubleshooting & Support
  • Integrating with Salesforce
  • Extending Heroku
  • Platform API
  • Pipelines Using the Platform API

Pipelines Using the Platform API

English — 日本語に切り替える

Last updated March 09, 2022

Table of Contents

  • Creating a pipeline
  • Adding apps to a pipeline
  • Inspecting a pipeline
  • Finding which pipeline an app belongs to
  • Finding a pipeline
  • Performing a promotion

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

Keep reading

  • Platform API

Feedback

Log in to submit feedback.

Setting Up Apps Using the Platform API Platform API Reference

Information & Support

  • Getting Started
  • Documentation
  • Changelog
  • Compliance Center
  • Training & Education
  • Blog
  • Podcasts
  • Support Channels
  • Status

Language Reference

  • Node.js
  • Ruby
  • Java
  • PHP
  • Python
  • Go
  • Scala
  • Clojure

Other Resources

  • Careers
  • Elements
  • Products
  • Pricing

Subscribe to our monthly newsletter

Your email address:

  • RSS
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku Blog
    • Heroku News Blog
    • Heroku Engineering Blog
  • Heroku Podcasts
  • Twitter
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku
    • Heroku Status
  • Facebook
  • Instagram
  • Github
  • LinkedIn
  • YouTube
Heroku is acompany

 © Salesforce.com

  • heroku.com
  • Terms of Service
  • Privacy
  • Cookies
  • Cookie Preferences