Pipelines API

List pipelines

Returns a paginated list of an organization’s pipelines.

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

Required scope: read_pipelines

Success response: 200 OK

Get a pipeline

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

Required scope: read_pipelines

Success response: 200 OK

Create a pipeline

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

The resulting pipeline:

Picture of the build pipeline that is created

Required request body properties:

nameThe name of the pipeline.

Example: "New Pipeline"

repositoryThe repository URL.

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

stepsAn array of the build pipeline steps.

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

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

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

Optional request body properties:

descriptionThe pipeline description.

Example: "📦 A testing pipeline"

envThe pipeline environment variables.

Example: {"KEY":"value"}

provider_settingsThe source provider settings.

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

skip_queued_branch_buildsSkip 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_filterA branch filter pattern to limit which branches intermediate build skipping applies to.

Example: "!master"
Default: null

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

Example: true
Default: false

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

Example: "develop prs/*"
Default: null

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

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

Required scope: write_pipelines

Success response: 201 Created

Error responses:

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

Update a pipeline

Updates one or more properties of an existing pipeline:

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

Optional request body properties:

nameThe name of the pipeline.

Example: "New Pipeline"

descriptionThe pipeline description.

Example: "📦 A testing pipeline"

repositoryThe repository URL.

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

stepsAn array of the build pipeline steps.

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

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

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

envThe pipeline environment variables.

Example: {"KEY":"value"}

provider_settingsThe source provider settings.

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

skip_queued_branch_buildsSkip 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_filterA branch filter pattern to limit which branches intermediate build skipping applies to.

Example: "!master"
Default: null

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

Example: true
Default: false

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

Example: "develop prs/*"
Default: null

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

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

Required scope: write_pipelines

Success response: 200 OK

Error responses:

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

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