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": {
}
}
]
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": {
}
}
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: |
---|---|
repository |
The repository URL. Example: |
configuration |
The YAML pipeline that consists of the build pipeline steps. Example: |
Optional request body properties:
branch_configuration |
A branch filter pattern to limit which pushed branches trigger builds on this pipeline. Example: |
---|---|
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: |
cancel_running_branch_builds_filter |
A branch filter pattern to limit which branches intermediate build cancelling applies to. Example: |
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: |
description |
The pipeline description. Example: |
provider_settings |
The source provider settings. See the Provider Settings section for accepted properties. Example: |
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: |
skip_queued_branch_builds_filter |
A branch filter pattern to limit which branches intermediate build skipping applies to. Example: |
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:
team_uuids parameter.
Example:
|
visibility |
Whether the pipeline is visible to everyone, including users outside this organization. Example: |
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: |
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:

Required request body properties:
name |
The name of the pipeline. Example: |
---|---|
repository |
The repository URL. Example: |
steps |
An array of the build pipeline steps. Script: Wait for all previous steps to finish: Block pipeline (see the job unblock API): |
Optional request body properties:
branch_configuration |
A branch filter pattern to limit which pushed branches trigger builds on this pipeline. Example: |
---|---|
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: |
cancel_running_branch_builds_filter |
A branch filter pattern to limit which branches intermediate build cancelling applies to. Example: |
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: |
description |
The pipeline description. Example: |
env |
The pipeline environment variables. Example: |
provider_settings |
The source provider settings. See the Provider Settings section for accepted properties. Example: |
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: |
skip_queued_branch_builds_filter |
A branch filter pattern to limit which branches intermediate build skipping applies to. Example: |
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:
team_uuids parameter.
Example:
|
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: |
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: |
---|---|
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: |
cancel_running_branch_builds_filter |
A branch filter pattern to limit which branches intermediate build cancelling applies to. Example: |
default_branch |
The name of the branch to prefill when new builds are created or triggered in Buildkite.
Example: |
description |
The pipeline description. Example: |
env |
The pipeline environment variables. Example: |
name |
The name of the pipeline. Example: |
provider_settings |
The source provider settings. See the Provider Settings section for accepted properties. Example: |
repository |
The repository URL. Example: |
configuration |
The YAML pipeline that consists of the build pipeline steps. Example: |
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: |
skip_queued_branch_builds_filter |
A branch filter pattern to limit which branches intermediate build skipping applies to. Example: |
visibility |
Whether the pipeline is visible to everyone, including users outside this organization. Example: |
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: |
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: |
---|---|
filter_condition |
The conditions under which this pipeline will trigger a build. See the Using conditionals guide for more information.
Example: |
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: |
---|---|
build_branches |
Whether to create builds when branches are pushed
Values: |
build_tags |
Whether to create builds when tags are pushed.
Values: |
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: |
---|---|
pull_request_branch_filter_enabled |
Whether to limit the creation of builds to specific branches or patterns.
Values: |
pull_request_branch_filter_configuration |
The branch filtering pattern. Only pull requests on branches matching this pattern will cause builds to be created.
Example: |
skip_builds_for_existing_commits |
Whether to skip creating a new build if a build for the commit and branch already exists.
Values: |
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: |
build_tags |
Whether to create builds when tags are pushed.
Values: |
publish_commit_status |
Whether to update the status of commits in Bitbucket or GitHub.
Values: |
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: |
Additional properties available for GitHub:
trigger_mode |
What type of event to trigger builds on.
Values: |
---|---|
build_pull_request_forks |
Whether to create builds for pull requests from third-party forks.
Values: |
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: |
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: |
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: |