Pipeline templates API

Enterprise feature

Pipeline templates are only available on an Enterprise plan.

The pipeline templates API allows admins to create and manage pipeline templates for an organization. Non-admins can only read or assign pipeline templates marked as available by organization admins.

Pipeline template data model

uuid UUID of the pipeline template
graphql_id GraphQL ID of the pipeline template
name Name of the pipeline template
description Description of the pipeline template
configuration YAML step configuration for the pipeline template
available When set to true, non-admins can assign the pipeline template to pipelines
Default: false
url Canonical API URL of the pipeline template
web_url URL of the pipeline template on Buildkite
created_at When the pipeline template was created
created_by User who created the pipeline template
updated_at When the pipeline template was created
updated_by User who last updated the pipeline template

List pipeline templates

Returns a list of an organization's pipeline templates.

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

[
  {
    "uuid": "018a86cc-db73-7d15-8c68-5023cf8d64c3",
    "graphql_id": "UGlwZWxpbmVUZW1wbGF0ZS0tLTAxOGE4NmNjLWRiNzMtN2QxNS04YzY4LTUwMjNjZjhkNjRjMw==",
    "name": "Build template",
    "description": "Shared build steps configuration",
    "configuration": "steps:\n  - label: \"🔨 Build\"\n    command: \"scripts/build.sh\"",
    "available": false,
    "url": "http:///api.buildkite.com/v2/organizations/acme-inc/pipeline-templates/018a86cc-db73-7d15-8c68-5023cf8d64c3",
    "web_url": "http://www.buildkite.com/organizations/acme-inc/pipeline-templates/018a86cc-db73-7d15-8c68-5023cf8d64c3",
    "created_at": "2023-05-03T04:17:55.867Z",
    "created_by": {
      "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
      "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
      "name": "Sam Kim",
      "email": "sam@example.com",
      "avatar_url": "https://www.gravatar.com/avatar/example",
      "created_at": "2013-05-03T04:17:55.867Z"
    },
    "updated_at": "2023-06-12T04:17:55.867Z",
    "updated_by": {
      "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
      "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
      "name": "Sam Kim",
      "email": "sam@example.com",
      "avatar_url": "https://www.gravatar.com/avatar/example",
      "created_at": "2013-05-03T04:17:55.867Z"
    }
  }
]

Required scope: read_pipeline_templates

Success response: 200 OK

Get a pipeline template

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

{
  "uuid": "018a86cc-db73-7d15-8c68-5023cf8d64c3",
  "graphql_id": "UGlwZWxpbmVUZW1wbGF0ZS0tLTAxOGE4NmNjLWRiNzMtN2QxNS04YzY4LTUwMjNjZjhkNjRjMw==",
  "name": "Build template",
  "description": "Shared build steps configuration",
  "configuration": "steps:\n  - label: \"🔨 Build\"\n    command: \"scripts/build.sh\"",
  "available": false,
  "url": "http:///api.buildkite.com/v2/organizations/acme-inc/pipeline-templates/018a86cc-db73-7d15-8c68-5023cf8d64c3",
  "web_url": "http://www.buildkite.com/organizations/acme-inc/pipeline-templates/018a86cc-db73-7d15-8c68-5023cf8d64c3",
  "created_at": "2023-05-03T04:17:55.867Z",
  "created_by": {
    "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
    "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2023-08-29T10:10:03.000Z"
  },
   "updated_at": "2023-06-12T04:17:55.867Z",
  "updated_by": {
    "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
    "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2013-05-03T04:17:55.867Z"
  }
}

Required scope: read_pipeline_templates

Success response: 200 OK

Create a pipeline template

curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/pipeline-templates" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "🔨 Build",
    "description": "Shared build steps configuration",
    "configuration": "steps:\n  - label: \"🔨 Build\"\n    command: \"scripts/build.sh\"",
    "available": true,
  }'

{
  "uuid": "018a86cc-db73-7d15-8c68-5023cf8d64c3",
  "graphql_id": "UGlwZWxpbmVUZW1wbGF0ZS0tLTAxOGE4NmNjLWRiNzMtN2QxNS04YzY4LTUwMjNjZjhkNjRjMw==",
  "name": "Build template",
  "description": "Shared build steps configuration",
  "configuration": "steps:\n  - label: \"🔨 Build\"\n    command: \"scripts/build.sh\"",
  "available": true,
  "url": "http:///api.buildkite.com/v2/organizations/acme-inc/pipeline-templates/018a86cc-db73-7d15-8c68-5023cf8d64c3",
  "web_url": "http://www.buildkite.com/organizations/acme-inc/pipeline-templates/018a86cc-db73-7d15-8c68-5023cf8d64c3",
  "created_at": "2023-05-03T04:17:55.867Z",
  "created_by": {
    "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
    "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2023-08-29T10:10:03.000Z"
  },
  "updated_at": "2023-06-12T04:17:55.867Z",
  "updated_by": {
    "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
    "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2013-05-03T04:17:55.867Z"
  }
}

Required request body properties:

name Name for the pipeline template.
Example: "Build template"
configuration YAML step configuration for the pipeline template.
Example: "steps:\n - command: "scripts/build.sh"

Optional request body properties:

description Description for the pipeline template.
Example: "Shared build steps configuration"
available When set to true, non-admins can assign the pipeline template to pipelines.
Example: false

Required scope: write_pipeline_templates

Success response: 201 Created

Error responses:

422 Unprocessable Entity { "message": "Validation failed: Reason for failure" }

Update a pipeline template

curl -H "Authorization: Bearer $TOKEN" \
  -X PATCH "https://api.buildkite.com/v2/organizations/{org.slug}/pipeline-templates/{uuid}" \
  -H "Content-Type: application/json" \
  -d '{ "available": true }'

{
  "uuid": "018a86cc-db73-7d15-8c68-5023cf8d64c3",
  "graphql_id": "UGlwZWxpbmVUZW1wbGF0ZS0tLTAxOGE4NmNjLWRiNzMtN2QxNS04YzY4LTUwMjNjZjhkNjRjMw==",
  "name": "Build template",
  "description": "Shared build steps configuration",
  "configuration": "steps:\n  - label: \"🔨 Build\"\n    command: \"scripts/build.sh\"",
  "available": true,
  "url": "http:///api.buildkite.com/v2/organizations/acme-inc/pipeline-templates/018a86cc-db73-7d15-8c68-5023cf8d64c3",
  "web_url": "http://www.buildkite.com/organizations/acme-inc/pipeline-templates/018a86cc-db73-7d15-8c68-5023cf8d64c3",
  "created_at": "2023-05-03T04:17:55.867Z",
  "created_by": {
    "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
    "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2023-08-29T10:10:03.000Z"
  },
  "updated_at": "2023-06-12T04:17:55.867Z",
  "updated_by": {
    "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
    "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2013-05-03T04:17:55.867Z"
  }
}

Optional request body properties:

name Name for the pipeline template.
Example: "Build template"
description Description for the pipeline template.
Example: "Shared build steps configuration"
configuration YAML step configuration for the pipeline template.
Example: "steps:\n - command: "scripts/build.sh"
available When set to true, non-admins can assign the pipeline template to pipelines.
Example: false

Required scope: write_pipeline_templates

Success response: 200 OK

Error responses:

422 Unprocessable Entity { "message": "Validation failed: Reason for failure" }

Delete a pipeline template

A pipeline template can only be deleted when it is not assigned to any pipelines. Ensure you remove the pipeline template from all pipelines before trying to delete it.

curl -H "Authorization: Bearer $TOKEN" \
  -X DELETE "https://api.buildkite.com/v2/organizations/{org.slug}/pipeline-templates/{uuid}"

Required scope: write_pipeline_templates

Success response: 204 No Content

Error responses:

422 Unprocessable Entity { "message": "Reason the pipeline template couldn't be deleted" }