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",
    "graphql_id": "UGlwZWxpbmUtLS1lOTM4ZGQxYy03MDgwLTQ4ZmQtOGQyMC0yNmQ4M2E0ZjNkNDg=",
    "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": "main",
    "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_by": {
      "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
      "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
      "name": "Keith Pitt",
      "email": "keith@buildkite.com",
      "avatar_url": "https://www.gravatar.com/avatar/e14f55d3f939977cecbf51b64ff6f861",
      "created_at": "2013-08-29T10:10:03.000Z"
    },
    "created_at": "2013-09-03 13:24:38 UTC",
    "archived_at": null,
    "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": "main feature/*",
        "env": { },
        "timeout_in_minutes": null,
        "agent_query_rules": [ ]
      }
    ],
    "env": {
    }
  }
]

Webhook URL

The response only includes a webhook URL in provider.webhook_url if the user has edit permissions for the pipeline. Otherwise, the field returns with an empty string.

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",
  "graphql_id": "UGlwZWxpbmUtLS1lOTM4ZGQxYy03MDgwLTQ4ZmQtOGQyMC0yNmQ4M2E0ZjNkNDg=",
  "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": "main",
  "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_by": {
    "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
    "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
    "name": "Keith Pitt",
    "email": "keith@buildkite.com",
    "avatar_url": "https://www.gravatar.com/avatar/e14f55d3f939977cecbf51b64ff6f861",
    "created_at": "2013-08-29T10:10:03.000Z"
  },
  "created_at": "2013-09-03 13:24:38 UTC",
  "archived_at": null,
  "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": "main feature/*",
      "env": { },
      "timeout_in_minutes": null,
      "agent_query_rules": [ ]
    }
  ],
  "env": {
  }
}

Webhook URL

The response only includes a webhook URL in pipeline.provider.webhook_url if the user has edit permissions for the pipeline. Otherwise, the field returns with an empty string.

Required scope: read_pipelines

Success response: 200 OK

Create a YAML pipeline

YAML pipelines are the recommended way to manage your pipelines. To create a YAML pipeline using this endpoint, set the configuration key in your json request body to an the YAML you want in your pipeline.

For example, to create a pipeline called "My Pipeline" containing the following command step

steps:
 - command: "script/release.sh"
   name: "Build :package:"

make the following POST request, substituting your organization slug instead of {org.slug}. Make sure to escape the quotes (") in your YAML, and to replace line breaks with \n:

curl -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines" \
  -H "Content-Type: application/json" \
  -d '{
      "name": "My Pipeline X",
      "repository": "git@github.com:acme-inc/my-pipeline.git",
      "configuration": "env:\n \"FOO\": \"bar\"\nsteps:\n - command: \"script/release.sh\"\n   \"name\": \"Build 📦\""
    }'

When setting pipeline configuration using the API, you must pass in a string that Buildkite parses as valid YAML, escaping quotes and line breaks.

To avoid writing an entire YAML file in a single string, you can place a pipeline.yml file in a .buildkite directory at the root of your repo, and use the pipeline upload command in your configuration to tell Buildkite where to find it. This means you only need the following:

"configuration": "steps:\n - command: \"buildkite-agent pipeline upload\""

The response contains information about your new pipeline:

{
  "id": "ad93b461-96ab-4a1e-9281-260ead506a0e",
  "graphql_id": "UGlwZWxpbmUtLS1hZDkzYjQ2MS05NmFiLTRhMWUtOTI4MS0yNjBlYWQ1MDZhMGU=",
  "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline-x",
  "web_url": "https://buildkite.com/acme-inc/my-pipeline-x",
  "name": "My Pipeline X",
  "description": null,
  "slug": "my-pipeline-x",
  "repository": "git@github.com:acme-inc/my-pipeline.git",
  "cluster_id": null,
  "branch_configuration": null,
  "default_branch": "main",
  "skip_queued_branch_builds": false,
  "skip_queued_branch_builds_filter": null,
  "cancel_running_branch_builds": false,
  "cancel_running_branch_builds_filter": null,
  "allow_rebuilds": true,
  "provider": {
    "id": "github",
    "settings": {
      "trigger_mode": "code",
      "build_pull_requests": true,
      "pull_request_branch_filter_enabled": false,
      "skip_builds_for_existing_commits": false,
      "skip_pull_request_builds_for_existing_commits": true,
      "build_pull_request_ready_for_review": false,
      "build_pull_request_labels_changed": false,
      "build_pull_request_forks": false,
      "prefix_pull_request_fork_branch_names": true,
      "build_branches": true,
      "build_tags": false,
      "cancel_deleted_branch_builds": false,
      "publish_commit_status": true,
      "publish_commit_status_per_step": false,
      "separate_pull_request_statuses": false,
      "publish_blocked_as_pending": false,
      "use_step_key_as_commit_status": false,
      "filter_enabled": false,
      "repository": "acme-inc/my-pipeline"
    },
    "webhook_url": "https://webhook.buildkite.com/deliver/fe08e0f823297a158fc4ca2bfddd6ea3ced92b5167a658a0bb"
  },
  "builds_url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline-x/builds",
  "badge_url": "https://badge.buildkite.com/05bf6d997d16c993ae6180ed7d85d29c9be8f8d8f37ac96477.svg",
  "created_by": {
    "id": "3cc415b8-3d63-4b9a-acb0-c120dbcb231c",
    "graphql_id": "VXNlci0tLTNjYzQxNWI4LTNkNjMtNGI5YS1hY2IwLWMxMjBkYmNiMjMxYw==",
    "name": "Sam Wright",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/3536621b97b6d9d39488202709317051",
    "created_at": "2020-02-14T16:57:23.153Z"
  },
  "created_at": "2021-05-06T14:54:21.088Z",
  "archived_at": null,
  "env": {
    "FOO": "bar"
  },
  "scheduled_builds_count": 0,
  "running_builds_count": 0,
  "scheduled_jobs_count": 0,
  "running_jobs_count": 0,
  "waiting_jobs_count": 0,
  "visibility": "private",
  "tags": null,
  "configuration": "env:\n \"FOO\": \"bar\"\n\"steps\":\n - command: \"script/release.sh\"\n   \"name\": \"Build 📦\"",
  "steps": [{
    "type": "script",
    "name": "Build 📦",
    "command": "script/release.sh",
    "artifact_paths": null,
    "branch_configuration": null,
    "env": {},
    "timeout_in_minutes": null,
    "agent_query_rules": [],
    "concurrency": null,
    "parallelism": null
  }]
}

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"
configuration The YAML pipeline that consists of the build pipeline steps.

Example: "steps:\n - command: \"script/release.sh\"\n"

Optional request body properties:

branch_configuration

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

Example: "main 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: "main"
description

The pipeline description.

Example: "📦 A testing 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 }
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: "!main"
Default: null
teams

An array of team UUIDs to add this pipeline to. Allows you to specify the access level for the pipeline in a team. The available access level options are:

  • read_only
  • build_and_read
  • manage_build_and_read
You can find your team's UUID either using the GraphQL API, or on the Settings page for a team. This property is only available if your organization has enabled Teams. Once your organization enables Teams, only administrators can create pipelines without providing team UUIDs. Replaces deprecated team_uuids parameter.

Example:

teams: {
  "14e9501c-69fe-4cda-ae07-daea9ca3afd3": "read_only"
  "3f195bcd-28f2-4e1a-bcff-09f3543e5abf": "build_and_read"
  "5b6c4a01-8e4f-49a3-bf88-be0d47ef9c0a": "manage_build_and_read"
}
visibility

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

Example: "public"
Default: "private"
cluster_id The ID of the cluster the pipeline should run in. Set to null to remove the pipeline from a cluster.
You'll need to enable clusters for your organization to use this feature.

Example: "42f1a7da-812d-4430-93d8-1cc7c33a6bcf"

Required scope: write_pipelines

Success response: 201 Created

Error responses:

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

Create a visual step pipeline

YAML pipelines are the recommended way to manage your pipelines but if you're still using visual steps you can add them by setting the steps key in your json request body to an array of steps:

curl -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines" \
  -H "Content-Type: application/json" \
  -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": "main",
        "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": "main",
        "trigger_async": true
      }
    ]
  }'

The response contains information about your new pipeline:

{
  "id": "14e9501c-69fe-4cda-ae07-daea9ca3afd3",
  "graphql_id": "UGlwZWxpbmUtLS1lOTM4ZGQxYy03MDgwLTQ4ZmQtOGQyMC0yNmQ4M2E0ZjNkNDg=",
  "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": "main"
  "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,
  "builtype": "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": "main",
      "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": "main",
        "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.

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

Optional request body properties:

branch_configuration

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

Example: "main 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: "main"
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: "!main"
Default: null
teams

An array of team UUIDs to add this pipeline to. Allows you to specify the access level for the pipeline in a team. The available access level options are:

  • read_only
  • build_and_read
  • manage_build_and_read
You can find your team's UUID either using the GraphQL API, or on the Settings page for a team. This property is only available if your organization has enabled Teams. Once your organization enables Teams, only administrators can create pipelines without providing team UUIDs. Replaces deprecated team_uuids parameter.

Example:

teams: {
  "14e9501c-69fe-4cda-ae07-daea9ca3afd3": "read_only",
  "5b6c4a01-8e4f-49a3-bf88-be0d47ef9c0a": "manage_build_and_read"
}
cluster_id The ID of the cluster the pipeline should run in. Set to null to remove the pipeline from a cluster.
You'll need to enable clusters for your organization to use this feature.

Example: "42f1a7da-812d-4430-93d8-1cc7c33a6bcf"

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.

To update a pipeline's YAML steps, make a PATCH request to the pipelines endpoint, passing the configuration attribute in the request body:

curl -X PATCH "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "repository": "git@github.com:acme-inc/new-repo.git",
    "configuration": "steps:\n  - command: \"new.sh\"\n    agents:\n    - \"myqueue=true\""
  }'

Patch requests can only update attributes already present in the pipeline YAML.

{
  "id": "14e9501c-69fe-4cda-ae07-daea9ca3afd3",
  "graphql_id": "UGlwZWxpbmUtLS1lOTM4ZGQxYy03MDgwLTQ4ZmQtOGQyMC0yNmQ4M2E0ZjNkNDg=",
  "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": "main",
  "default_branch": "main"
  "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",
  "archived_at": null,
  "configuration": "steps:\n  - command: \"new.sh\"\n    agents:\n    - \"something=true\"",
  "steps": [
    {
      "type": "script",
      "name": null,
      "command": "new.sh",
      "artifact_paths": null,
      "branch_configuration": null,
      "env": {},
      "timeout_in_minutes": null,
      "agent_query_rules": [
        "myqueue=true"
      ],
      "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"
}

Optional request body properties:

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

Example: "main 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: "main"
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"
configuration The YAML pipeline that consists of the build pipeline steps.

Example: "steps:\n - command: \"new.sh\"\n agents:\n - \"myqueue=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: "!main"
Default: null
visibility Whether the pipeline is visible to everyone, including users outside this organization.

Example: "public"
Default: "private"
cluster_id The ID of the cluster the pipeline should run in. Set to null to remove the pipeline from a cluster.
You'll need to enable clusters for your organization to use this feature.

Example: "42f1a7da-812d-4430-93d8-1cc7c33a6bcf"

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.

Archive a pipeline

Archived pipelines are read-only, and are hidden from Pipeline pages by default. Builds, build logs, and artifacts are preserved.

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

{
  "id": "14e9501c-69fe-4cda-ae07-daea9ca3afd3",
  "graphql_id": "UGlwZWxpbmUtLS1lOTM4ZGQxYy03MDgwLTQ4ZmQtOGQyMC0yNmQ4M2E0ZjNkNDg=",
  "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": "main",
  "default_branch": "main"
  "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",
  "archived_at": "2021-06-01 08:23:35 UTC",
  "configuration": "steps:\n  - command: \"new.sh\"\n    agents:\n    - \"something=true\"",
  "steps": [
    {
      "type": "script",
      "name": null,
      "command": "new.sh",
      "artifact_paths": null,
      "branch_configuration": null,
      "env": {},
      "timeout_in_minutes": null,
      "agent_query_rules": [
        "myqueue=true"
      ],
      "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"
}

Required scope: write_pipelines

Success response: 200 OK

Error responses:

403 Forbidden { "message": "Forbidden" }
422 Unprocessable Entity { "message": "Pipeline could not be archived." }

Unarchive a pipeline

Unarchived pipelines are editable, and are shown on the Pipeline pages.

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

{
  "id": "14e9501c-69fe-4cda-ae07-daea9ca3afd3",
  "graphql_id": "UGlwZWxpbmUtLS1lOTM4ZGQxYy03MDgwLTQ4ZmQtOGQyMC0yNmQ4M2E0ZjNkNDg=",
  "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": "main",
  "default_branch": "main"
  "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",
  "archived_at": null,
  "configuration": "steps:\n  - command: \"new.sh\"\n    agents:\n    - \"something=true\"",
  "steps": [
    {
      "type": "script",
      "name": null,
      "command": "new.sh",
      "artifact_paths": null,
      "branch_configuration": null,
      "env": {},
      "timeout_in_minutes": null,
      "agent_query_rules": [
        "myqueue=true"
      ],
      "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"
}

Required scope: write_pipelines

Success response: 200 OK

Error responses:

403 Forbidden { "message": "Forbidden" }
422 Unprocessable Entity { "message": "Pipeline could not be unarchived." }

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

Add a webhook

Create an GitHub webhook for an existing pipeline that is configured using our GitHub App. Pushes to the linked GitHub repository will trigger builds.

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

Required scope: write_pipelines

Success response: 201 CREATED

Error responses:

403 Forbidden { "message": "Forbidden" }
422 Unprocessable Entity { "message": "Auto-creating webhooks is not supported for your repository." }
422 Unprocessable Entity { "message": "Webhooks could not be created for your repository." }

Provider settings properties

The Create a YAML 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.

Properties available for all providers:

filter_enabled Whether filter conditions are used for this pipeline.

Values: true, false
filter_condition The conditions under which this pipeline will trigger a build. See the Using conditionals guide for more information.

Example: "build.pull_request.base_branch =~ /main/"

Bitbucket Cloud, Bitbucket Server, GitHub, and GitHub Enterprise all have optional provider_settings.

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_branches Whether to create builds when branches are pushed

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_builds_for_existing_commits Whether to skip creating a new build if a build for the commit and branch already exists.

Values: true, false
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 available for GitHub:

trigger_mode What type of event to trigger builds on.
  • code creates builds when code is pushed to GitHub.
  • deployment creates builds when a deployment is created with the GitHub Deployments API.
  • fork creates builds when the GitHub repository is forked.
  • none will not create any builds based on GitHub activity.

Values: code, deployment, fork, none
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 main branch from some-user will become some-user:main.

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: true, false