Pipelines API

List pipelines

Returns a paginated list of an organization’s pipelines.

curl "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines"
[
  {
    "id": "849411f9-9e6d-4739-a0d8-e247088e9b52",
    "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline",
    "web_url": "https://buildkite.com/acme-inc/my-pipeline",
    "name": "My Pipeline",
    "slug": "my-pipeline",
    "repository": "git@github.com:acme-inc/my-pipeline.git",
    "branch_configuration": null,
    "default_branch": "master",
    "provider": {
      "id": "github",
      "webhook_url": "https://webhook.buildkite.com/deliver/xxx",
      "settings": {
        "publish_commit_status": true,
        "build_pull_requests": true,
        "build_pull_request_forks": false,
        "build_tags": false,
        "publish_commit_status_per_step": false,
        "repository": "acme-inc/my-pipeline",
        "trigger_mode": "code"
      }
    },
    "skip_queued_branch_builds": false,
    "skip_queued_branch_builds_filter": null,
    "cancel_running_branch_builds": false,
    "cancel_running_branch_builds_filter": null,
    "builds_url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline/builds",
    "badge_url": "https://badge.buildkite.com/58b3da999635d0ad2daae5f784e56d264343eb02526f129bfb.svg",
    "created_at": "2013-09-03 13:24:38 UTC",
    "scheduled_builds_count": 0,
    "running_builds_count": 0,
    "scheduled_jobs_count": 0,
    "running_jobs_count": 0,
    "waiting_jobs_count": 0,
    "visibility": "private",
    "steps": [
      {
        "type": "script",
        "name": "Test ✅",
        "command": "script/test.sh",
        "artifact_paths": "results/*",
        "branch_configuration": "master feature/*",
        "env": { },
        "timeout_in_minutes": null,
        "agent_query_rules": [ ]
      }
    ],
    "env": {
    }
  }
]

Required scope: read_pipelines

Success response: 200 OK

Get a pipeline

curl "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{slug}"
{
  "id": "849411f9-9e6d-4739-a0d8-e247088e9b52",
  "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline",
  "web_url": "https://buildkite.com/acme-inc/my-pipeline",
  "name": "My Pipeline",
  "description": "This pipeline is amazing! 🎉",
  "slug": "my-pipeline",
  "repository": "git@github.com:acme-inc/my-pipeline.git",
  "branch_configuration": null,
  "default_branch": "master",
  "provider": {
    "id": "github",
    "webhook_url": "https://webhook.buildkite.com/deliver/xxx",
    "settings": {
      "publish_commit_status": true,
      "build_pull_requests": true,
      "build_pull_request_forks": false,
      "build_tags": false,
      "publish_commit_status_per_step": false,
      "repository": "acme-inc/my-pipeline",
      "trigger_mode": "code"
    }
  },
  "skip_queued_branch_builds": false,
  "skip_queued_branch_builds_filter": null,
  "cancel_running_branch_builds": false,
  "cancel_running_branch_builds_filter": null,
  "builds_url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline/builds",
  "badge_url": "https://badge.buildkite.com/58b3da999635d0ad2daae5f784e56d264343eb02526f129bfb.svg",
  "created_at": "2013-09-03 13:24:38 UTC",
  "scheduled_builds_count": 0,
  "running_builds_count": 0,
  "scheduled_jobs_count": 0,
  "running_jobs_count": 0,
  "waiting_jobs_count": 0,
  "visibility": "private"
  "steps": [
    {
      "type": "script",
      "name": "Test ✅",
      "command": "script/test.sh",
      "artifact_paths": "results/*",
      "branch_configuration": "master feature/*",
      "env": { },
      "timeout_in_minutes": null,
      "agent_query_rules": [ ]
    }
  ],
  "env": {
  }
}

Required scope: read_pipelines

Success response: 200 OK

Create a pipeline

curl -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines" \
  -d '{
    "name": "My Pipeline",
    "repository": "git@github.com:acme-inc/my-pipeline.git",
    "steps": [
      {
        "type": "script",
        "name": "Build :package:",
        "command": "script/release.sh"
      },
      {
        "type": "waiter"
      },
      {
        "type": "script",
        "name": "Test :wrench:",
        "command": "script/release.sh",
        "artifact_paths": "log/*"
      },
      {
        "type": "manual",
        "label": "Deploy"
      },
      {
        "type": "script",
        "name": "Release :rocket:",
        "command": "script/release.sh",
        "branch_configuration": "master",
        "env": {
          "AMAZON_S3_BUCKET_NAME": "my-pipeline-releases"
        },
        "timeout_in_minutes": 10,
        "agent_query_rules": ["aws=true"]
      },
      {
        "type": "trigger",
        "label": "Deploy :ship:",
        "trigger_project_slug": "deploy",
        "trigger_commit": "HEAD",
        "trigger_branch": "master",
        "trigger_async": true
      }
    ]
  }'
{
  "id": "14e9501c-69fe-4cda-ae07-daea9ca3afd3",
  "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline",
  "web_url": "https://buildkite.com/acme-inc/my-pipeline",
  "name": "My Pipeline",
  "description": null,
  "slug": "my-pipeline",
  "repository": "git@github.com:acme-inc/my-pipeline.git",
  "branch_configuration": null,
  "default_branch": "master"
  "provider": {
    "id": "github",
    "webhook_url": "https://webhook.buildkite.com/deliver/xxx",
    "settings": {
      "publish_commit_status": true,
      "build_pull_requests": true,
      "build_pull_request_forks": false,
      "build_tags": false,
      "publish_commit_status_per_step": false,
      "repository": "acme-inc/my-pipeline",
      "trigger_mode": "code"
    }
  },
  "skip_queued_branch_builds": false,
  "skip_queued_branch_builds_filter": null,
  "cancel_running_branch_builds": false,
  "cancel_running_branch_builds_filter": null,
  "builds_url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline/builds",
  "badge_url": "https://badge.buildkite.com/58b3da999635d0ad2daae5f784e56d264343eb02526f129bfb.svg",
  "created_at": "2018-08-15T05:47:45.813Z",
  "steps": [
    {
      "type": "script",
      "name": "Build :package:",
      "command": "script/release.sh",
      "artifact_paths": null,
      "branch_configuration": null,
      "env": {},
      "timeout_in_minutes": null,
      "agent_query_rules": [],
      "concurrency": null,
      "parallelism": null
    },
    {
      "type": "waiter"
    },
    {
      "type": "script",
      "name": "Test :wrench:",
      "command": "script/release.sh",
      "artifact_paths": "log/*",
      "branch_configuration": null,
      "env": {},
      "timeout_in_minutes": null,
      "agent_query_rules": [

      ],
      "concurrency": null,
      "parallelism": null
    },
    {
      "type": "manual",
      "label": "Deploy"
    },
    {
      "type": "script",
      "name": "Release :rocket:",
      "command": "script/release.sh",
      "artifact_paths": null,
      "branch_configuration": "master",
      "env": {
        "AMAZON_S3_BUCKET_NAME": "my-pipeline-releases"
      },
      "timeout_in_minutes": 10,
      "agent_query_rules": [
        "aws=true"
      ],
      "concurrency": null,
      "parallelism": null
    },
    {
      "type": "trigger",
      "label": "Deploy :ship:",
      "pipeline": "deploy",
      "build": {
        "message": null,
        "branch": "master",
        "commit": "HEAD",
        "env": null
      },
      "async": true,
      "branch_configuration": null,
      "concurrency": null,
      "parallelism": null
    }
  ],
  "env": {
  },
  "scheduled_builds_count": 0,
  "running_builds_count": 0,
  "scheduled_jobs_count": 0,
  "running_jobs_count": 0,
  "waiting_jobs_count": 0,
  "visibility": "private"
}

The resulting pipeline:

Image of the pipeline steps that are created in the Buildkite UI

Required request body properties:

name The name of the pipeline.

Example: "New Pipeline"

repository The repository URL.

Example: "git@github.com:acme-inc/my-pipeline.git"

steps An array of the build pipeline steps.

Command: { "type": "script", "name": "Script", "command": "command.sh" }

Wait for all previous steps to finish: { "type": "waiter" }

Block pipeline (see the job unblock API): { "type": "manual" }

Trigger pipeline: { "type": "trigger", "trigger_project_slug": "a-pipeline" }

Optional request body properties:

branch_configuration A branch filter pattern to limit which pushed branches trigger builds on this pipeline.

Example: "master feature/*"
Default: null

cancel_running_branch_builds Cancel intermediate builds. When a new build is created on a branch, any previous builds that are running on the same branch will be automatically canceled.

Example: true
Default: false

cancel_running_branch_builds_filter A branch filter pattern to limit which branches intermediate build cancelling applies to.

Example: "develop prs/*"
Default: null

default_branch The name of the branch to prefill when new builds are created or triggered in Buildkite. It is also used to filter the builds and metrics shown on the Pipelines page.

Example: "master"

description The pipeline description.

Example: "📦 A testing pipeline"

env The pipeline environment variables.

Example: {"KEY":"value"}

provider_settings The source provider settings. See the Provider Settings section for accepted properties.

Example: { "publish_commit_status": true, "build_pull_request_forks": true }

skip_queued_branch_builds Skip intermediate builds. When a new build is created on a branch, any previous builds that haven't yet started on the same branch will be automatically marked as skipped.

Example: true
Default: false

skip_queued_branch_builds_filter A branch filter pattern to limit which branches intermediate build skipping applies to.

Example: "!master"
Default: null

team_uuids An array of team UUIDs to add this pipeline to. You can find your team’s UUID either via the GraphQL API, or on the settings page for a team. This property is only available if your organization has enabled Teams.

Example: ["14e9501c-69fe-4cda-ae07-daea9ca3afd3"]

Required scope: write_pipelines

Success response: 201 Created

Error responses:

422 Unprocessable Entity{ "message": "Validation Failed", "errors": [ ... ] }

Update a pipeline

Updates one or more properties of an existing pipeline:

curl -X PATCH "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{slug}" \
  -d '{
    "repository": "git@github.com:acme-inc/new-repo.git"
  }'
{
  "id": "14e9501c-69fe-4cda-ae07-daea9ca3afd3",
  "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline",
  "web_url": "https://buildkite.com/acme-inc/my-pipeline",
  "name": "My Pipeline",
  "description": null,
  "slug": "my-pipeline",
  "repository": "git@github.com:acme-inc/new-repo.git",
  "branch_configuration": "master",
  "default_branch": "master"
  "provider": {
    "id": "github",
    "webhook_url": "https://webhook.buildkite.com/deliver/xxx",
    "settings": {
      "publish_commit_status": true,
      "build_pull_requests": true,
      "build_pull_request_forks": false,
      "build_tags": false,
      "publish_commit_status_per_step": false,
      "repository": "acme-inc/new-repo",
      "trigger_mode": "code"
    }
  },
  "skip_queued_branch_builds": false,
  "skip_queued_branch_builds_filter": null,
  "cancel_running_branch_builds": false,
  "cancel_running_branch_builds_filter": null,
  "builds_url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline/builds",
  "badge_url": "https://badge.buildkite.com/58b3da999635d0ad2daae5f784e56d264343eb02526f129bfb.svg",
  "created_at": "2015-03-01 06:44:40 UTC",
  "steps": [
    {
      "type": "script",
      "name": "Build :package:",
      "command": "script/release.sh",
      "artifact_paths": "pkg/*",
      "branch_configuration": null,
      "env": { },
      "timeout_in_minutes": null,
      "agent_query_rules": [ ]
    }
  ],
  "env": {
  },
  "scheduled_builds_count": 0,
  "running_builds_count": 0,
  "scheduled_jobs_count": 0,
  "running_jobs_count": 0,
  "waiting_jobs_count": 0,
  "visibility": "private"
}

Optional request body properties:

branch_configuration A branch filter pattern to limit which pushed branches trigger builds on this pipeline.

Example: "master feature/*"
Default: null

cancel_running_branch_builds Cancel intermediate builds. When a new build is created on a branch, any previous builds that are running on the same branch will be automatically canceled.

Example: true
Default: false

cancel_running_branch_builds_filter A branch filter pattern to limit which branches intermediate build cancelling applies to.

Example: "develop prs/*"
Default: null

default_branch The name of the branch to prefill when new builds are created or triggered in Buildkite.

Example: "master"

description The pipeline description.

Example: "📦 A testing pipeline"

env The pipeline environment variables.

Example: {"KEY":"value"}

name The name of the pipeline.

Example: "New Pipeline"

provider_settings The source provider settings. See the Provider Settings section for accepted properties.

Example: { "publish_commit_status": true, "build_pull_request_forks": true }

repository The repository URL.

Example: "git@github.com/org/repo.git"

steps An array of the build pipeline steps.

Script: { "type": "script", "name": "Script", "command": "command.sh" }

Wait for all previous steps to finish: { "type": "waiter" }

Block pipeline (see the job unblock API): { "type": "manual" }

skip_queued_branch_builds Skip intermediate builds. When a new build is created on a branch, any previous builds that haven't yet started on the same branch will be automatically marked as skipped.

Example: true
Default: false

skip_queued_branch_builds_filter A branch filter pattern to limit which branches intermediate build skipping applies to.

Example: "!master"
Default: null

visibility Whether the pipeline is visible to everyone, including users outside this organization.

Example: "public"
Default: "private"

Required scope: write_pipelines

Success response: 200 OK

Error responses:

422 Unprocessable Entity{ "message": "Validation Failed", "errors": [ ... ] }

To update a pipeline's teams, please use the GraphQL API.

Delete a pipeline

curl -X DELETE "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{slug}"

Required scope: write_pipelines

Success response: 204 No Content

Provider settings properties

The Create Pipeline and Update Pipeline endpoints accept a provider_settings property, which allows you to configure how the pipeline is triggered based on source code provider events. Each pipeline provider’s supported settings are below.

Bitbucket Cloud, Bitbucket Server, GitHub, and GitHub Enterprise all have optional provider_settings. Other source providers such as Gitlab do not have optional settings available.

Properties available for Bitbucket Server:

build_pull_requests Whether to create builds for commits that are part of a Pull Request.

Values: true, false

build_tags Whether to create builds when tags are pushed.

Values: true, false

Properties available for Bitbucket Cloud, GitHub, and GitHub Enterprise:

build_pull_requests Whether to create builds for commits that are part of a Pull Request.

Values: true, false

pull_request_branch_filter_enabled Whether to limit the creation of builds to specific branches or patterns.

Values: true, false

pull_request_branch_filter_configuration The branch filtering pattern. Only pull requests on branches matching this pattern will cause builds to be created.

Example: "features/*"

skip_pull_request_builds_for_existing_commits Whether to skip creating a new build for a pull request if an existing build for the commit and branch already exists.

Values: true, false

build_tags Whether to create builds when tags are pushed.

Values: true, false

publish_commit_status Whether to update the status of commits in Bitbucket or GitHub.

Values: true, false

publish_commit_status_per_step Whether to create a separate status for each job in a build, allowing you to see the status of each job directly in Bitbucket or GitHub.

Values: true, false

Additional properties availble for GitHub:

trigger_mode What type of event to trigger builds on. Code will create builds when code is pushed to GitHub. Deployment will create builds when a deployment is created with the GitHub Deployments API. Fork will create builds when the GitHub repository is forked. None will not create any builds based on GitHub activity.

Values: code, deployment, fork, none

filter_enabled Whether filter conditions are being used for this step.

Values: true, false

filter_condition The conditions under which this step will run. See the Using Conditionals guide for more information.

Example: "build.message != 'skip'"

build_pull_request_forks Whether to create builds for pull requests from third-party forks.

Values: true, false

prefix_pull_request_fork_branch_names Prefix branch names for third-party fork builds to ensure they don't trigger branch conditions. For example, the master branch from some-user will become some-user:master.

Values: true, false

separate_pull_request_statuses Whether to create a separate status for pull request builds, allowing you to require a passing pull request build in your required status checks in GitHub.

Values: true, false

publish_blocked_as_pending The status to use for blocked builds. Pending can be used with required status checks to prevent merging pull requests with blocked builds.

Values: passed, pending