# Pipelines API

The pipelines API endpoint consists of several endpoints that allow you to manage:

- Pipelines, along with their [builds](/docs/apis/rest-api/builds) and [schedules](/docs/apis/rest-api/pipeline-schedules).
- A build's [annotations](/docs/apis/rest-api/annotations), [artifacts](/docs/apis/rest-api/artifacts), and [jobs](/docs/apis/rest-api/jobs).

This section of the REST API documentation also contains several other endpoints that allow you to manage other aspects of Buildkite functionality associated with your pipelines, such as:

- [Clusters](/docs/apis/rest-api/clusters), including the management of [queues](/docs/apis/rest-api/clusters/queues), [agent tokens](/docs/apis/rest-api/clusters/agent-tokens), [cluster maintainers](/docs/apis/rest-api/clusters/maintainers), and [Buildkite secrets](/docs/apis/rest-api/clusters/secrets).
- [Agents](/docs/apis/rest-api/agents) themselves.

## Pipeline data model



| `id` | UUID of the pipeline |
| --- | --- |
| `graphql_id` | [GraphQL ID](/docs/apis/graphql-api#graphql-ids) of the pipeline |
| `url` | Canonical API URL of the pipeline |
| `web_url` | URL of the pipeline on Buildkite |
| `name` | Name of the pipeline |
| `description` | Description of the pipeline |
| `slug` | URL slug of the pipeline |
| `repository` | URL of the source code repository |
| `cluster_id` | UUID of the cluster the pipeline belongs to (if using clusters) |
| `branch_configuration` | Branch filter pattern for limiting which branches trigger builds |
| `clone_mirror_url` | Optional repository URL that agents use as a Git clone mirror. When set, agents receive this URL in `BUILDKITE_GIT_REMOTE_MIRROR_URL`. |
| `default_branch` | Default branch for the pipeline |
| `skip_queued_branch_builds` | Whether to skip intermediate builds on the same branch (`true`, `false`) |
| `skip_queued_branch_builds_filter` | Branch filter pattern for skip queued builds behavior |
| `cancel_running_branch_builds` | Whether to cancel running builds when a new build is created on the same branch (`true`, `false`) |
| `cancel_running_branch_builds_filter` | Branch filter pattern for cancel running builds behavior |
| `allow_rebuilds` | Whether rebuilds are allowed (`true`, `false`) |
| `provider` | Source control provider settings (includes `id`, `webhook_url`, and `settings`) |
| `builds_url` | API URL for the pipeline's builds |
| `badge_url` | URL for the pipeline's build status badge |
| `created_by` | User who created the pipeline |
| `created_at` | When the pipeline was created |
| `archived_at` | When the pipeline was archived (if archived) |
| `env` | Environment variables configured for the pipeline |
| `scheduled_builds_count` | Number of currently scheduled builds |
| `running_builds_count` | Number of currently running builds |
| `scheduled_jobs_count` | Number of currently scheduled jobs |
| `running_jobs_count` | Number of currently running jobs |
| `waiting_jobs_count` | Number of jobs waiting for agents |
| `visibility` | Visibility of the pipeline: `private` or `public` |
| `steps` | Array of step configurations (for non-YAML pipelines) |
| `configuration` | YAML pipeline configuration (for YAML pipelines) |



> 📘 Clone mirror availability
> Clone mirrors must be enabled for your organization. When enabled, responses return <code>clone_mirror_url</code> as <code>null</code> for pipelines without a configured mirror. When disabled, responses omit the property for pipelines without a configured mirror but continue to return previously configured mirror URLs. Create and update requests reject <code>clone_mirror_url</code> values that are not blank when the feature is disabled. You can submit <code>null</code> or an empty string to remove an existing mirror even when the feature is disabled.

## List pipelines

Returns a [paginated list](/docs/rest-api#pagination) of an organization's pipelines.

> 📘
> Filtering pipelines by creation date sorts results from newest to oldest.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines"
```

```json
[
  {
    "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 :white_check_mark:",
        "command": "script/test.sh",
        "artifact_paths": "results/*",
        "branch_configuration": "main feature/*",
        "env": { },
        "timeout_in_minutes": null,
        "agent_query_rules": [ ]
      }
    ],
    "env": {
    }
  }
]
```

Optional [query string parameters](/docs/api#query-string-parameters):



| `name` | Filters the results by the pipeline name. Supports partial matches and is case insensitive. _Example:_ `?name=agent` |
| --- | --- |
| `repository` | Filters the results by the repository URL of the source repository. Supports partial matches and is case insensitive. _Example:_ `?repository=agent` |



> 📘 Webhook URL
> The response only includes a webhook URL in `provider.webhook_url` if the user has edit permissions for the pipeline and the API access token has the `write_pipelines` scope. Otherwise, the field returns with an empty string.

Required scope: `read_pipelines`

Success response: `200 OK`

## Get a pipeline

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{slug}"
```

```json
{
  "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! :tada:",
  "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 :white_check_mark:",
      "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 and the API access token has the `write_pipelines` scope. 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](/docs/pipelines/tutorials/pipeline-upgrade). To create a YAML pipeline using this endpoint, set the `configuration` key in your json request body to the YAML you want in your pipeline.

For GitHub Actions Compatibility, prefer [GitHub Actions setup in the Buildkite interface](/docs/pipelines/migration/run-github-actions-workflows#add-a-github-actions-workflow-to-a-pipeline-create-a-github-actions-pipeline). To provision the equivalent using this API, [create the pipeline with the GitHub Actions provider settings, then create its dedicated pipeline trigger](/docs/pipelines/migration/run-github-actions-workflows#add-a-github-actions-workflow-to-a-pipeline-configure-an-equivalent-pipeline-manually). This endpoint doesn't create the trigger or its signed repository webhook automatically.

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

```yaml
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`:

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

> 📘
> 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 <code>pipeline.yml</code> file in a <code>.buildkite</code> directory at the root of your repo, and use the <code>pipeline upload</code> command in your configuration to tell Buildkite where to find it. This means you only need the following:
> <code>"configuration": "steps:\n - command: \"buildkite-agent pipeline upload\""</code>

The response contains information about your new pipeline:

```json
{
  "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,
  "pipeline_template_uuid": 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 :package:\"",
  "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
  }]
}
```

Required [request body properties](/docs/api#request-body-properties):



| `name` | The name of the pipeline. _Example:_ `"New Pipeline"` |
| --- | --- |
| `cluster_id` | The ID value of the cluster the pipeline will be associated with. _Example:_ `"018e5a22-d14c-7085-bb28-db0f83f43a1c"` |
| `repository` | The repository URL. _Example:_ `"git@github.com:acme-inc/my-pipeline.git"` |
| `configuration` | The YAML pipeline that consists of the build pipeline steps. Must be non-empty. A missing or blank value returns a `422` error. Pipelines using a [pipeline template](/docs/apis/rest-api/pipeline-templates) for their steps do not need to supply this field. _Example:_ `"steps:\n - command: \"script/release.sh\"\n"` |



Optional [request body properties](/docs/api#request-body-properties):



| `allow_rebuilds` | Enables rebuilding of existing builds. _Example:_ `false` _Default:_ `true` |
| --- | --- |
| `branch_configuration` | A [branch filter pattern](/docs/pipelines/configure/workflows/branch-configuration#pipeline-level-branch-filtering) 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](/docs/pipelines/configure/workflows/branch-configuration#branch-pattern-examples) to limit which branches intermediate build canceling applies to. _Example:_ `"develop prs/*"` _Default:_ `null` |
| `clone_mirror_url` | An optional repository URL for agents to use as a Git clone mirror. When set, agents receive this URL in `BUILDKITE_GIT_REMOTE_MIRROR_URL`. The URL must not contain credentials, query parameters, or fragments. _Example:_ `"git@mirror.example.com:acme/my-pipeline.git"` _Default:_ `null` |
| `color` | A color hex code to represent this pipeline. _Example:_ `"#FF5733"` |
| `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"` |
| `default_command_step_timeout` | The default timeout in minutes for all command steps in this pipeline. This can still be overridden in any command step. _Example:_ `30` |
| `description` | The pipeline description. _Example:_ `"\:package\: A testing pipeline"` |
| `emoji` | An emoji to represent this pipeline. _Example:_ `"\:rocket\:"` (will be rendered as "🚀") |
| `maximum_command_step_timeout` | The maximum timeout in minutes for all command steps in this pipeline. Any command step without a timeout or with a timeout greater than this value will be capped at this limit. _Example:_ `120` |
| `pipeline_template_uuid` |
| `provider_settings` | The source provider settings. See the [Provider Settings](#provider-settings-properties) 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](/docs/pipelines/configure/workflows/branch-configuration#branch-pattern-examples) to limit which branches intermediate build skipping applies to. _Example:_ `"!main"` _Default:_ `null` |
| `slug` | A custom identifier for the pipeline. If provided, this slug will be used as the pipeline's URL path instead of automatically converting the pipeline name. If the value is `null`, the pipeline name will be used to generate the slug. _Example:_ `"my-custom-pipeline-slug"` |
| `tags` | An array of strings representing [tags](/docs/pipelines/configure/tags) to add to this pipeline. Emojis, using the `:emoji:` string syntax, are also supported. _Example:_`["\:terraform\:", "testing"]` |
| `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](/docs/apis/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:_ ```javascript 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"` |



Required scope: `write_pipelines`

Success response: `201 Created`

Error responses:



| `422 Unprocessable Entity` | `{ "message": "Validation Failed", "errors": [ ... ] }`. When `configuration` is missing or blank, the error includes `{ "field": "configuration", "code": "Step configuration is missing, expected `steps: { yaml: \"...\" }`" }`. |
| --- | --- |



### Deriving a pipeline slug from the pipeline's name

Pipeline slugs are derived from the pipeline name you provide when the pipeline is created (unless you use the optional `slug` parameter to specify a custom slug).

This derivation process involves converting all space characters (including consecutive ones) in the pipeline's name to single hyphen `-` characters, and all uppercase characters to their lowercase counterparts. Therefore, pipeline names of either `Hello there friend` or `Hello    There Friend` are converted to the slug `hello-there-friend`.

The maximum permitted length for a pipeline slug is 100 characters.

> 📘
> The following regular expression is used to derive and convert the pipeline name to its slug:
> `/\A[a-zA-Z0-9]+[a-zA-Z0-9\-]*\z/`

Any attempt to create a new pipeline with a name that matches an existing pipeline's name results in an error.

## Create a visual step pipeline

YAML pipelines are the recommended way to [manage your pipelines](/docs/pipelines/tutorials/pipeline-upgrade) 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:

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Pipeline",
    "cluster_id": "xxx",
    "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:

```json
{
  "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:

<div style="max-width: 487px"><div class="responsive-image-container"><img alt="Image of the pipeline steps that are created in the Buildkite UI" src="/docs/assets/pipeline-example-DOJ3BKUR.png" /></div></div>

Required [request body properties](/docs/api#request-body-properties):



| `name` | The name of the pipeline. _Example:_ `"New Pipeline"` |
| --- | --- |
| `cluster_id` | The ID value of the cluster the pipeline will be associated with. _Example:_ `"018e5a22-d14c-7085-bb28-db0f83f43a1c"` |
| `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](/docs/apis/rest-api/jobs#unblock-a-job)):_ `{ "type": "manual" }` |



Optional [request body properties](/docs/api#request-body-properties):



| `branch_configuration` | A [branch filter pattern](/docs/pipelines/configure/workflows/branch-configuration#pipeline-level-branch-filtering) 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](/docs/pipelines/configure/workflows/branch-configuration#branch-pattern-examples) to limit which branches intermediate build canceling applies to. _Example:_ `"develop prs/*"` _Default:_ `null` |
| `clone_mirror_url` | An optional repository URL for agents to use as a Git clone mirror. When set, agents receive this URL in `BUILDKITE_GIT_REMOTE_MIRROR_URL`. The URL must not contain credentials, query parameters, or fragments. _Example:_ `"git@mirror.example.com:acme/my-pipeline.git"` _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:_ `":package: A testing pipeline"` |
| `env` | The pipeline environment variables. _Example:_ `{"KEY":"value"}` |
| `pipeline_template_uuid` |
| `provider_settings` | The source provider settings. See the [Provider Settings](#provider-settings-properties) 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](/docs/pipelines/configure/workflows/branch-configuration#branch-pattern-examples) to limit which branches intermediate build skipping applies to. _Example:_ `"!main"` _Default:_ `null` |
| `slug` | A custom identifier for the pipeline. If provided, this slug will be used as the pipeline's URL path instead of automatically converting the pipeline name. If the value is `null`, the pipeline name will be used to generate the slug. _Example:_ `"my-custom-pipeline-slug"` |
| `tags` | An array of strings representing [tags](/docs/pipelines/configure/tags) to add to this pipeline. Emojis, using the `:emoji:` string syntax, are also supported. _Example:_`["\:terraform\:", "testing"]` |
| `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](/docs/apis/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:_ ```javascript teams: { "14e9501c-69fe-4cda-ae07-daea9ca3afd3": "read_only", "5b6c4a01-8e4f-49a3-bf88-be0d47ef9c0a": "manage_build_and_read" } ``` |



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:

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -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\"",
    "tags": ["\:terraform\:", "testing"]
  }'
```

> 🚧
> Two attributes below behave differently for YAML pipelines. This endpoint ignores `env`. To set environment variables, get the current `configuration` for the pipeline, add or update the top-level `env` key, then PATCH the complete `configuration` back. This endpoint only rejects `steps` with a `422` error when `configuration` is absent from the request. If both are present, it ignores `steps` and applies `configuration` instead. Neither restriction applies to [visual step pipelines](#create-a-visual-step-pipeline), where `env` and `steps` are top-level, persisted settings.

```json
{
  "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](/docs/api#request-body-properties):



| `allow_rebuilds` | Enables rebuilding of existing builds. _Example:_ `false` _Default:_ `true` |
| --- | --- |
| `branch_configuration` | A [branch filter pattern](/docs/pipelines/configure/workflows/branch-configuration#pipeline-level-branch-filtering) 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](/docs/pipelines/configure/workflows/branch-configuration#branch-pattern-examples) to limit which branches intermediate build canceling applies to. _Example:_ `"develop prs/*"` _Default:_ `null` |
| `clone_mirror_url` | An optional repository URL for agents to use as a Git clone mirror. When set, agents receive this URL in `BUILDKITE_GIT_REMOTE_MIRROR_URL`. Set to `null` to remove the mirror. The URL must not contain credentials, query parameters, or fragments. _Example:_ `"git@mirror.example.com:acme/my-pipeline.git"` _Default:_ `null` |
| `color` | A color hex code to represent this pipeline. _Example:_ `"#FF5733"` |
| `cluster_id` |
| `configuration` | The YAML pipeline that consists of the build pipeline steps. Setting this attribute replaces the entire configuration for the pipeline, so include all existing steps and settings, not just the ones you want to change. _Example:_ `"steps:\n - command: \"new.sh\"\n agents:\n - \"myqueue=true\""` |
| `default_branch` | The name of the branch to prefill when new builds are created or triggered in Buildkite. _Example:_ `"main"` |
| `default_command_step_timeout` | The default timeout in minutes for all command steps in this pipeline. This can still be overridden in any command step. _Example:_ `30` |
| `description` | The pipeline description. _Example:_ `"\:package\: A testing pipeline"` |
| `env` | Environment variables for the pipeline. This only applies to visual step pipelines. For pipelines with YAML steps, this endpoint ignores `env`. To set environment variables, get the current `configuration` for the pipeline, add or update the top-level `env` key, then PATCH the complete `configuration` back. _Example:_ `{"KEY":"value"}` |
| `emoji` | An emoji to represent this pipeline. _Example:_ `"\:rocket\:"` (will be rendered as "🚀") |
| `maximum_command_step_timeout` | The maximum timeout in minutes for all command steps in this pipeline. Any command step without a timeout or with a timeout greater than this value will be capped at this limit. _Example:_ `120` |
| `name` | The name of the pipeline. If you provide a new name without a `slug` parameter, the slug will be automatically updated to match the new name. _Example:_ `"New Pipeline"` |
| `pipeline_template_uuid` |
| `provider_settings` | The source provider settings. See the [Provider Settings](#provider-settings-properties) 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"` |
| `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](/docs/pipelines/configure/workflows/branch-configuration#branch-pattern-examples) to limit which branches intermediate build skipping applies to. _Example:_ `"!main"` _Default:_ `null` |
| `slug` | A custom identifier for the pipeline. This slug will be used as the pipeline's URL path. It can only contain alphanumeric characters or dashes and cannot begin with a dash. The slug updates whenever the pipeline name changes. If you don't provide a slug when you update the pipeline name, the slug will be automatically generated from the new pipeline name. _Example:_ `"my-custom-pipeline-slug"` |
| `steps` | An array of visual steps to replace the existing steps in the pipeline. This only applies to visual step pipelines. For pipelines with YAML steps, this endpoint rejects `steps` with a `422` error when `configuration` is absent from the request. If both are present, it ignores `steps` and applies `configuration` instead. _Example:_ `[{"type": "script", "name": "Build", "command": "script/release.sh"}]` |
| `tags` | An array of strings representing [tags](/docs/pipelines/configure/tags) to modify on this pipeline. Emojis, using the `:emoji:` string syntax, are also supported. _Example:_`["\:terraform\:", "testing"]` |
| `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](/docs/apis/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:_ ```javascript 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"` |



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 <a href="/docs/apis/graphql-api">GraphQL API</a>.

## Archive a pipeline

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

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{slug}/archive"
```

```json
{
  "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.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{slug}/unarchive"
```

```json
{
  "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

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -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 a GitHub webhook for an existing pipeline that is configured using our GitHub App. Pushes to the linked GitHub repository will trigger builds.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -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." }` This error might be returned because an existing webhook has already been created for this pipeline, and the additional webhook could not be created as it is outside the intended scope of this feature. |



## GitHub webhook processing

These endpoints let you get, enable, or disable native incoming GitHub webhook processing for a pipeline. They are only available for GitHub and GitHub Enterprise pipelines. Your organization must be enrolled in the expanded webhook triggers feature.

These controls don't affect [GitHub Actions pipeline triggers](/docs/apis/rest-api/pipeline-triggers#create-a-pipeline-trigger-create-a-github-actions-pipeline-trigger), which process their own deliveries. When [migrating to server-side workflow dispatch](/docs/pipelines/migration/run-github-actions-workflows#migrate-to-server-side-dispatch), disable native webhook processing to avoid duplicate builds without deleting repository webhooks used by other pipelines.

> 📘 Feature availability
> These endpoints return `404 Not Found` if your organization is not enrolled in the expanded webhook triggers feature, or if the pipeline is not connected to a GitHub or GitHub Enterprise repository.

### GitHub webhook processing data model



| `url` | Canonical API URL of the GitHub webhook processing state |
| --- | --- |
| `enabled` | Whether incoming GitHub webhook processing is enabled for this pipeline |
| `disabled_at` | The time webhook processing was disabled, or `null` when enabled |
| `disabled_by` | The name of the user who disabled webhook processing, or `null` when enabled |



### Get GitHub webhook processing state

```bash
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{slug}/github-webhooks"
```

Required scope: `read_pipelines`

Required permission: [**Full Access**](/docs/pipelines/security/permissions#manage-teams-and-permissions-pipeline-level-permissions) to the pipeline

Success response: `200 OK`

```json
{
  "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline/github-webhooks",
  "enabled": true,
  "disabled_at": null,
  "disabled_by": null
}
```

### Enable GitHub webhook processing

Enables incoming webhook processing for the pipeline. This operation is idempotent. If webhook processing is already enabled, the endpoint returns the current state without changing it.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X PUT "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{slug}/github-webhooks"
```

Required scope: `write_pipelines`

Required permission: **Full Access** to the pipeline

Success response: `200 OK`

```json
{
  "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline/github-webhooks",
  "enabled": true,
  "disabled_at": null,
  "disabled_by": null
}
```

### Disable GitHub webhook processing

Disables incoming webhook processing for the pipeline and records who disabled it and when. This operation is idempotent. If webhook processing is already disabled, the endpoint returns the current state without changing it.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X DELETE "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{slug}/github-webhooks"
```

Required scope: `write_pipelines`

Required permission: **Full Access** to the pipeline

Success response: `200 OK`

```json
{
  "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline/github-webhooks",
  "enabled": false,
  "disabled_at": "2024-01-15T09:30:00.000Z",
  "disabled_by": "Jane Doe"
}
```

## Provider settings properties

The [Create a YAML pipeline](#create-a-yaml-pipeline) and [Update pipeline](#update-a-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](/docs/pipelines/configure/conditionals) guide for more information. _Example:_ `"build.pull_request.base_branch =~ /main/"` |



Bitbucket Cloud, Bitbucket Server, GitLab, GitLab Self-Managed, GitHub, GitHub Enterprise, Origin, and Code Storage all have optional `provider_settings`.

> 📘 Origin and Code Storage provider settings
> Origin provider settings require the pipeline to use a repository selected from a connected Origin installation. Code Storage provider settings require a Code Storage HTTPS repository URL. Connect the [Code Storage organization](/docs/pipelines/source-control/code-storage) to enable push builds, hosted-agent checkout, and Git notes delivery. The Code Storage integration is in public preview.

Properties available for Bitbucket Server:



| `build_branches` | Whether to create builds when branches are pushed. _Values:_ `true`, `false` |
| --- | --- |
| `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_branches` | Whether to create builds when branches are pushed. _Values:_ `true`, `false` |
| --- | --- |
| `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` |
| `ignore_default_branch_pull_requests` | Whether to skip creating a new build for a pull request if its source branch is the default branch. _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` |
| `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` |



Properties available for GitLab and GitLab Self-Managed:



| `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` |
| `build_pull_requests` | Whether to create builds for merge requests. _Values:_ `true`, `false` |
| `build_pull_request_merge` | Whether to build the [merged results](https://docs.gitlab.com/ci/pipelines/merged_results_pipelines/) commit instead of the head commit of the merge request source branch. Requires `build_pull_requests` to be `true`. _Values:_ `true`, `false` |
| `build_pull_request_base_branch_changed` | Whether to rebuild merge requests when the target branch is updated. Requires `build_pull_request_merge` to be `true`. _Values:_ `true`, `false` |
| `publish_commit_status` | Whether to update the status of commits in GitLab. _Values:_ `true`, `false` |



Properties available for Origin:



| `build_branches` | Whether to create builds when branches are pushed. _Values:_ `true`, `false` |
| --- | --- |
| `build_pull_requests` | Whether to create builds when pull requests are opened or updated. _Values:_ `true`, `false` |
| `build_pull_request_ready_for_review` | Whether to create a build when a draft pull request is marked ready for review. Respects `skip_pull_request_builds_for_existing_commits`. Requires `build_pull_requests` to be `true`. _Values:_ `true`, `false`. _Default:_ `false` |
| `build_pull_request_reopened` | Whether to create a build when a pull request is reopened, even if its commit and branch already built. Requires `build_pull_requests` to be `true`. _Values:_ `true`, `false`. _Default:_ `false` |
| `build_pull_request_base_branch_changed` | Whether to create a build when a pull request changes target branch, even if its commit and branch already built. Does not create a build when the target branch receives new commits. Requires `build_pull_requests` to be `true`. _Values:_ `true`, `false`. _Default:_ `false` |
| `build_pull_request_edited` | Whether to create a build when a pull request title, description, or target branch changes, even if its commit and branch already built. Either this setting or `build_pull_request_base_branch_changed` enables target-branch-change builds. Requires `build_pull_requests` to be `true`. _Values:_ `true`, `false`. _Default:_ `false` |
| `build_pull_request_labels_changed` | Whether to create builds when labels are added to or removed from a pull request. Respects `skip_pull_request_builds_for_existing_commits`. Requires `build_pull_requests` to be `true` and pull request labels support enabled for your Buildkite organization. _Values:_ `true`, `false`. _Default:_ `false` |
| `build_pull_request_review_submitted` | Whether to create a build of the reviewed commit when a submitted review approves, requests changes, or comments on a pull request. Works independently of `build_pull_requests` and ignores `skip_pull_request_builds_for_existing_commits`. Requires review access for the Origin installation. Review dismissals and reviews on closed or merged pull requests do not create builds. _Values:_ `true`, `false`. _Default:_ `false` |
| `skip_pull_request_builds_for_existing_commits` | Whether to skip a pull request build when an earlier webhook build exists for the same commit and branch. Enabled reopen, edit, target-branch-change, and submitted-review events can rebuild the same commit regardless of this setting. Webhook retries and matching push and pull request head notifications do not create duplicate pull request builds. _Values:_ `true`, `false`. _Default:_ `true` |
| `build_tags` | Whether to create builds when tags are pushed. _Values:_ `true`, `false` |
| `publish_commit_status` | Whether to publish build results to Origin using the Checks API. The property name is retained for API compatibility. _Values:_ `true`, `false` |



Properties available for Code Storage:



| `build_branches` | Whether to create builds when branches are pushed. Defaults to `true`. _Values:_ `true`, `false` |
| --- | --- |
| `build_tags` | Whether to create builds when tags are pushed. Defaults to `false`. _Values:_ `true`, `false` |
| `publish_git_notes` | Whether to publish build status to Code Storage as [Git notes](/docs/pipelines/source-control/code-storage#publish-build-status-as-git-notes). Defaults to `true`. Setting this to `false` stops future notes but does not remove existing notes. _Values:_ `true`, `false` |



Code Storage does not support `build_pull_requests` or `publish_commit_status`. It reports build status using Git notes. Code Storage triggers builds through an organization-level webhook, so there is no per-pipeline webhook URL.

Additional properties available for GitHub and GitHub Enterprise:



| `build_pull_request_base_branch_changed` | Whether to create builds for pull requests when the base branch is changed. _Values:_ `true`, `false` |
| --- | --- |
| `build_pull_request_forks` | Whether to create builds for pull requests from third-party forks. _Values:_ `true`, `false` |
| `build_pull_request_labels_changed` | Whether to create builds for pull requests when labels are added or removed. Requires `build_pull_requests` to be `true`. _Values:_ `true`, `false` |
| `build_pull_request_ready_for_review` | Whether to create builds for pull requests that are ready for review. Requires `build_pull_requests` to be `true`. _Values:_ `true`, `false` |
| `build_pull_request_stacks` | Whether to create a build when a pull request is added to a stack. The initial `opened` event does not carry stack metadata and is processed as a normal pull request. Buildkite caches metadata from the later `stacked` event for subsequent builds, regardless of this setting. Requires `build_pull_requests` to be `true`. _Values:_ `true`, `false`. _Default:_ `false` |
| `build_pull_request_reopened` | Whether to create builds when a pull request is reopened. Requires `build_pull_requests` to be `true`. _Values:_ `true`, `false` |
| `build_pull_request_edited` | Whether to create builds when a pull request is edited (title, description, or base branch changed). Requires `build_pull_requests` to be `true`. _Values:_ `true`, `false` |
| `build_pull_request_converted_to_draft` | Whether to create builds when a pull request is converted to draft. Requires `build_pull_requests` to be `true`. _Values:_ `true`, `false` |
| `build_pull_request_review_requested` | Whether to create builds when a review is requested on a pull request. Requires `build_pull_requests` to be `true`. _Values:_ `true`, `false` |
| `build_check_run_completed` | Whether to create builds when a check run completes. The check runs from Buildkite Pipelines builds are automatically skipped to prevent loops. _Values:_ `true`, `false` |
| `build_pull_request_review_submitted` | Whether to create builds when a pull request review is submitted. _Values:_ `true`, `false` |
| `build_pull_request_review_dismissed` | Whether to create builds when a pull request review is dismissed. _Values:_ `true`, `false` |
| `build_release_published` | Whether to create builds when a GitHub release is published. _Values:_ `true`, `false` |
| `build_release_created` | Whether to create builds when a GitHub release is created. _Values:_ `true`, `false` |
| `build_release_released` | Whether to create builds when a GitHub release is released. _Values:_ `true`, `false` |
| `build_issue_comment_created` | Whether to create builds when a comment is posted on a pull request. Comments must match the configured command word (default: `/bk`) and come from a trusted author (owner, member, or collaborator). _Values:_ `true`, `false` |
| `issue_comment_command_word` | The command word that a PR comment must match to trigger a build. Only used when `build_issue_comment_created` is `true`. _Default:_ `/bk` |
| `build_deployment_status_created` | Whether to create builds when a GitHub deployment status is created. Requires the `deployment` trigger mode. Deployment statuses posted by Buildkite are automatically skipped to prevent loops. _Values:_ `true`, `false` |
| `build_pull_request_review_comment_created` | Whether to create builds when an inline diff comment is posted on a pull request. Comments must match the configured review comment command word and come from a trusted author (owner, member, or collaborator). _Values:_ `true`, `false` |
| `review_comment_command_word` | The command word that a PR review comment must match to trigger a build. Only used when `build_pull_request_review_comment_created` is `true`. _Default:_ `/bk` |
| `review_comment_match_mode` | How the review comment command word is matched against the comment body. `exact` requires the entire whitespace-trimmed comment to equal the command word; `contains` matches if the command word appears anywhere in the comment. Both modes are case-insensitive. _Values:_ `exact`, `contains`. _Default:_ `exact` |
| `issue_comment_match_mode` | How the issue comment command word is matched against the comment body. `exact` requires the entire whitespace-trimmed comment to equal the command word; `contains` matches if the command word appears anywhere in the comment. Both modes are case-insensitive. _Values:_ `exact`, `contains`. _Default:_ `exact` |
| `build_pull_request_dequeued` | Whether to create builds when a pull request is removed from a merge queue. Requires `build_pull_requests` to be `true`. _Values:_ `true`, `false` |
| `build_create_event` | Whether to create builds when a branch or tag is created. _Values:_ `true`, `false` |
| `cancel_deleted_branch_builds` | Whether to cancel running builds when a branch is deleted. _Values:_ `true`, `false` |
| `build_merge_group_checks_requested` | Whether to create merge queue builds for merge queue enabled GitHub repository with required status checks. _Values:_ `true`, `false` |
| `cancel_when_merge_group_destroyed` | Whether to cancel any running builds belonging to a removed merge group. _Values:_ `true`, `false` |
| `use_merge_group_base_commit_for_git_diff_base` | When enabled, agents performing a git diff to determine steps to upload based on `if_changed` comparisons will use the base commit that points to the previous merge group rather than the base branch. _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` |
| `publish_blocked_as_pending` | The status to use for blocked builds. `Pending` can be used with [required status checks](https://help.github.com/en/articles/enabling-required-status-checks) to prevent merging pull requests with blocked builds. _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](https://help.github.com/en/articles/enabling-required-status-checks) in GitHub. _Values:_ `true`, `false` |
| `build_pull_request_merge_commits` | Whether builds for pull requests target the latest test merge commit ref (`refs/pull/:pr_number/merge`) instead of the latest commit on the pull request branch. Requires `build_pull_requests` to be `true`. When enabling this, we recommend disabling `build_branches` so that commit statuses accurately reflect the state of the pull request. [Building the test merge commit](/docs/pipelines/source-control/github#running-builds-on-pull-requests-building-the-test-merge-commit) is currently in private preview. _Values:_ `true`, `false` |
| `skip_builds_for_existing_commits` | Whether to skip creating a new build if a build for the same commit already exists, regardless of branch. _Values:_ `true`, `false` |
| `skip_builds_for_closed_pull_requests` | Whether to skip creating a new build for a pull request when the pull request is closed or merged. Useful for ignoring late activity from automated housekeeping (such as label changes from bots) on closed pull requests. _Values:_ `true`, `false` |
| `use_step_key_as_commit_status` | Whether to use a job's `key` attribute in the GitHub commit status context instead of its label. Requires `publish_commit_status` and `publish_commit_status_per_step` to be `true`. _Values:_ `true`, `false` |
| `prevent_custom_statuses_from_using_buildkite_prefix` | Whether to prevent custom commit statuses configured using `notify:` from setting `context:` to a value that starts with `buildkite/`. When enabled, custom commit statuses must specify a `context:`. Effective enforcement also requires this feature to be enabled for your organization. When the feature is inactive, the setting is stored but not enforced. This feature is currently in private preview. Contact [Buildkite support](mailto:support@buildkite.com) to enable it for your organization. _Values:_ `true`, `false` |
| `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](https://developer.github.com/v3/repos/deployments/). `fork` creates builds when the GitHub repository is forked. `none` disables traditional GitHub build triggering. It doesn't disable [GitHub Actions pipeline triggers](/docs/apis/rest-api/pipeline-triggers#create-a-pipeline-trigger-create-a-github-actions-pipeline-trigger), which process their own deliveries. _Values:_ `code`, `deployment`, `fork`, `none` |



Additional properties available for GitHub:



| `github_workflow_access_tokens_enabled` | Whether jobs can request GitHub access tokens bounded by workflow permissions. This setting is not supported for GitHub Enterprise Server pipelines. The organization feature and this pipeline setting must both be enabled. See [credentials, secrets, and OIDC](/docs/pipelines/migration/run-github-actions-workflows#supported-functionality-and-limitations-credentials-secrets-and-oidc) for requirements and limitations. This feature is currently in private preview. Contact [Buildkite support](mailto:support@buildkite.com) to enable it for your organization. _Values:_ `true`, `false` |
| --- | --- |
| `build_issues` | Whether to create builds for GitHub issue activity, such as an issue being opened, edited, labeled, or closed. This setting is not supported for GitHub Enterprise Server pipelines. Only available for GitHub.com pipelines that use the full-access **GitHub** App. Builds run the repository's default branch at the exact commit resolved when Buildkite Pipelines processes the webhook delivery. Public issue authors can trigger these builds without a trusted-author check. See [running builds on issue activity](/docs/pipelines/source-control/github#running-builds-on-additional-github-events-running-builds-on-issue-activity) for details. This feature is currently in private preview. Contact [Buildkite support](mailto:support@buildkite.com) to enable it for your organization. _Values:_ `true`, `false` |


