Access policies for Buildkite secrets

Policy schema

Policies are defined as a list of policy rules in YAML. Each policy rule (beginning with a -) specifies one or more claims, all of which must be met for a build to access the Buildkite secret.

Each claim must specify one or more conditions. Conditions can be a single item or a list of strings. When a list of condition strings is provided on a claim, at least one of these string values must match for the claim to be met.

A single condition on each claim within a policy rule:

# All claims must be met. The build must be from the "frontend-pipeline" pipeline and built on the "main" branch.
- pipeline_slug: "frontend-pipeline"     # Claim 1 with a single condition
  build_branch: "main"                   # Claim 2 with a single condition

Multiple conditions on each claim within a policy rule:

This policy will grant access to builds running in the frontend-pipeline and the backend-pipeline running on either the main or develop branch.

# This rule grants access if:
# - The pipeline is EITHER "frontend-pipeline" OR "backend-pipeline"
#   AND
# - The branch is EITHER "main" OR "develop"
- pipeline_slug:                        # Claim 1 with two conditions
    - "frontend-pipeline"
    - "backend-pipeline"
  build_branch:                         # Claim 1 with two conditions
    - "main"
    - "develop"

Multiple policy rules:

This policy will grant access to builds in the frontend-pipeline running on the main branch, and will grant access to builds in the backend-pipeline running on the develop branch. It will not grant access to builds running in the frontend-pipeline on the develop branch.

# This rule grants access if:
# - The pipeline is "frontend-pipeline"
#   AND
# - The branch is "main"
- pipeline_slug: "frontend-pipeline"
  build_branch: "main"

# This rule grants access if:
# - The pipeline is "backend-pipeline"
#   AND
# - The branch is "develop"
- pipeline_slug: "backend-pipeline"
  build_branch: "develop"

First-party claims

First-party claims are ones whose values are generated by Buildkite. This makes these claims more secure than third-party claims.

Third-party claims

Third-party claims are ones whose values are provided by users or third-party tools. While these claims can be useful for controlling access, they are not as secure as first-party claims, which are generated by the Buildkite platform.

Example access policy

The following example access policy contains three rules with different levels of access control. Access to the secret is granted if the build matches all conditions in any one of these rules.

# This rule grants access if the build matches all five claims and their conditions.
- pipeline_slug: "my-pipeline"
  build_branch: "main"
  build_creator: "user@example.com"
  build_source: "webhook"
  build_creator_team: "123e4567-e89b-12d3-a456-426614174000"

# This rule grants access if:
# - pipeline_slug is "frontend-pipeline" OR "backend-pipeline"
# AND
# - build_branch is either "main" OR "develop"
- pipeline_slug:
    - "frontend-pipeline"
    - "backend-pipeline"
  build_branch:
    - "main"
    - "develop"

# This rule grants access if:
# - pipeline_slug is "public-pipeline"
# AND
# - build_branch is "main" or "release"
# AND
# - build_creator is "admin@example.com" or "deployer@example.com"
- pipeline_slug: "public-pipeline"
  build_branch:
    - "main"
    - "release"
  build_creator:
    - "admin@example.com"
    - "deployer@example.com"

Use case examples

Access policies can be tailored to fit a wide range of security and workflow requirements. Here are some practical examples of rules to help you get started.

Restrict secret access to the main branch of a pipeline

- pipeline_slug: "my-pipeline"
  build_branch: "main"

Restrict secret access to only Github merge queue builds

- pipeline_slug: "my-pipeline"
  build_branch: "gh-readonly-queue/*"

Only allow a chosen team to deploy from the main branch

- build_branch: "main"
  build_creator_team: "e2b7c3f4-1a5d-4e6b-9c8d-2f3a4b5c6d7e"

Add an access policy

A Buildkite secret's access policy can only be added (and modified) by cluster maintainers, as well as Buildkite organization administrators.

1. Select Agents in the global navigation to access the Clusters page.
2. Select the cluster in which to create the new Buildkite secret.
3. Select the secret you want to secure with an access policy.
4. Select the secret's Access tab.
5. In the Agent access section, select Restrict access to agents matching a policy.
6. Add your policy to the Policy field in YAML format.
7. Select Update agent access to save your changes.