Rules API

The rules API endpoint lets you create and manage rules in your organization.

Rules

Rules is a Buildkite feature that can do the following:

  • Grant access between Buildkite resources that would normally be restricted by cluster, visibility, or permissions.

  • Allows an action between a source resource and a target resource across your Buildkite organization. For example, allowing one pipeline's builds to trigger another pipeline's builds.

List rules

Returns a paginated list of an organization's rules.

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

[
  {
    "uuid": "42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
    "graphql_id": "Q2x1c3Rlci0tLTQyZjFhN2RhLTgxMmQtNDQzMC05M2Q4LTFjYzdjMzNhNmJjZg==",
    "organization_uuid": "f02d6a6f-7a0e-481d-9d6d-89b427aec48d",
    "url": "http://api.buildkite.com/v2/organizations/acme-inc/rules/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
    "type": "pipeline.trigger_build.pipeline",
    "source_type": "pipeline",
    "source_uuid": "16f3b56f-4934-4546-923c-287859851332",
    "target_type": "pipeline",
    "target_uuid": "d07d5d84-d1bd-479c-902c-ce8a01ce5aac",
    "effect": "allow",
    "action": "trigger_build",
    "created_at": "2024-08-26T03:22:45.555Z",
    "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-08-29T10:10:03.000Z"
    }
  }
]

Required scope: read_rules

Success response: 200 OK

Get a rule

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

{
  "uuid": "42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "graphql_id": "Q2x1c3Rlci0tLTQyZjFhN2RhLTgxMmQtNDQzMC05M2Q4LTFjYzdjMzNhNmJjZg==",
  "organization_uuid": "f02d6a6f-7a0e-481d-9d6d-89b427aec48d",
  "url": "http://api.buildkite.com/v2/organizations/acme-inc/rules/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "type": "pipeline.trigger_build.pipeline",
  "source_type": "pipeline",
  "source_uuid": "16f3b56f-4934-4546-923c-287859851332",
  "target_type": "pipeline",
  "target_uuid": "d07d5d84-d1bd-479c-902c-ce8a01ce5aac",
  "effect": "allow",
  "action": "trigger_build",
  "created_at": "2024-08-26T03:22:45.555Z",
  "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-08-29T10:10:03.000Z"
  }
}

Required scope: read_rules

Success response: 200 OK

Create a rule

curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/rules" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "pipeline.trigger_build.pipeline",
    "value": {
      "source_pipeline": "16f3b56f-4934-4546-923c-287859851332",
      "target_pipeline": "d07d5d84-d1bd-479c-902c-ce8a01ce5aac"
    }
  }'

{
  "uuid": "42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "graphql_id": "Q2x1c3Rlci0tLTQyZjFhN2RhLTgxMmQtNDQzMC05M2Q4LTFjYzdjMzNhNmJjZg==",
  "organization_uuid": "f02d6a6f-7a0e-481d-9d6d-89b427aec48d",
  "url": "http://api.buildkite.com/v2/organizations/acme-inc/rules/42f1a7da-812d-4430-93d8-1cc7c33a6bcf",
  "type": "pipeline.trigger_build.pipeline",
  "source_type": "pipeline",
  "source_uuid": "16f3b56f-4934-4546-923c-287859851332",
  "target_type": "pipeline",
  "target_uuid": "d07d5d84-d1bd-479c-902c-ce8a01ce5aac",
  "effect": "allow",
  "action": "trigger_build",
  "created_at": "2024-08-26T03:22:45.555Z",
  "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-08-29T10:10:03.000Z"
  }
}

Required request body properties:

type The rule type. Must match one of the available rule types.
Example:
  • "pipeline.trigger_build.pipeline"
    or
  • "pipeline.artifacts_read.pipeline"
value A JSON object containing the value fields for the rule. source_pipeline and target_pipeline fields accept either a pipeline UUID or a pipeline slug.
Example: {"source_pipeline": "16f3b56f-4934-4546-923c-287859851332", "target_pipeline": "d07d5d84-d1bd-479c-902c-ce8a01ce5aac"}

Required scope: write_rules

Success response: 201 Created

Error responses:

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

Delete a rule

Delete a rule.

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

Required scope: write_rules

Success response: 204 No Content

Error responses:

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