Rules overview

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.

The rules feature is currently in development, and is enabled on an opt-in basis for early access. To enable rules for your organization, please contact Buildkite's Support team at support@buildkite.com.

Rule types

Buildkite Pipelines supports two types of rules that allow one pipeline build to:

Trigger another pipeline build.
Read the artifacts generated by another pipeline build.

pipeline.trigger_build.pipeline

This rule type allows one pipeline to trigger another, where:

Both pipelines are in the same or different clusters.
One pipeline is public and another is private.

This rule type overrides the usual trigger step permissions checks on users and teams.

Rule Document format:

{
  "rule": "pipeline.trigger_build.pipeline",
  "value": {
    "source_pipeline": "pipeline-uuid-or-slug",
    "target_pipeline": "pipeline-uuid-or-slug",
    "conditions": [
      "source.build.branch == 'main'",
      "source.build.commit == target.trigger.commit"
    ]
  }
}

where:

source_pipeline is the UUID or slug of the pipeline that's allowed to trigger another pipeline.
target_pipeline is the UUID or slug of the pipeline that can be triggered by the source_pipeline's pipeline.
conditions is an optional array of conditionals that must be met to allow the source_pipeline's pipeline to trigger the target_pipeline's pipeline. Learn more about this in the following Conditions section.

Conditions

The optional conditions field allows you to specify an array of conditionals that must be met for the source pipeline (source_pipeline) to trigger the target pipeline (target_pipeline). In the example above, the rule would only allow triggering if the source pipeline's build branch is main and the commit of the source pipeline's build matches that of the target pipeline's trigger build. If no conditions are specified, triggering is allowed in all cases between the source and target pipelines. If any of the conditions are not met, triggering is not allowed, even if the default permissions would have allowed triggering. The conditions are evaluated using the Buildkite conditionals syntax.

In the pipeline.trigger_build.pipeline rule the available variables for conditions are:

Variable	Type	Description
`source.build.*`	`Build`	The triggering build in the source pipeline (contains the trigger step). This includes all the variables available for a build. Example variables available: `source.build.branch` - the branch of the source pipeline that the trigger step is targeting. `source.build.commit` - the commit of the source pipeline that the trigger step is targeting. `source.build.message` - the commit message of the source pipeline that the trigger step is targeting.
`source.target.branch`	`String`	The branch of the target pipeline that the trigger step is targeting.
`source.target.commit`	`String`	The commit of the target pipeline that the trigger step is targeting.
`source.target.message`	`String`	The commit message of the target pipeline that the trigger step is targeting.

Conditions are shown in error messages when access is denied.

Learn more about creating rules in Manage rules.

Example use case: cross-cluster pipeline triggering

Clusters may be used to separate the environments necessary for building and deploying an application. For example, a continuous integration (CI) pipeline has been set up in cluster A and likewise, a continuous deployment (CD) pipeline in cluster B. Ordinarily, pipelines in separate clusters are not able to trigger builds between each other due to the strict isolation of clusters.

However, a pipeline.trigger_build.pipeline rule would allow a trigger step in the CI pipeline of cluster A to target the CD pipeline in cluster B. Such rules would allow deployment to be triggered upon a successful CI build, while still maintaining the separation between the CI and CD agents in their respective clusters.

pipeline.artifacts_read.pipeline

This rule type allows one pipeline to access (that is, with read-only permissions) the artifacts built by another, where:

Both pipelines are in the same or different clusters.
One pipeline is public and another is private.

Rule Document format:

{
  "rule": "pipeline.artifacts_read.pipeline",
  "value": {
    "source_pipeline": "pipeline-uuid-or-slug",
    "target_pipeline": "pipeline-uuid-or-slug",
    "conditions": [
      "source.build.branch == target.build.branch",
    ]
  }
}

where:

source_pipeline is the UUID or slug of the pipeline that's allowed to access the artifacts from another pipeline.
target_pipeline is the UUID or slug of the pipeline whose artifacts can be accessed by jobs in the source_pipeline pipeline.
conditions is an optional array of conditionals that must be met to allow the jobs of the source_pipeline's pipeline to access the artifacts of the target_pipeline's pipeline. Learn more about this in the following Conditions section.

Conditions

The optional conditions field allows you to specify an array of conditionals that must be met for jobs of the source pipeline (source_pipeline) to access artifacts built by the target pipeline (target_pipeline). In the example above, the rule would only allow artifact access if the source pipeline's build branch matches the target pipeline's build branch. If no conditions are specified, artifact access is allowed in all cases between the source and target pipelines. If any of the conditions are not met, artifact access is not allowed, even if the default permissions would have allowed triggering. The conditions are evaluated using the Buildkite conditionals syntax.

In the pipeline.read_artifacts.pipeline rule the available variables for conditions are:

Variable Type Description

Variable	Type	Description
`source.build.*`	`Build`	The build in the source pipeline that is accessing the artifacts. This includes all the variables available for a build. Example variables available: `source.build.branch` - the branch of the source pipeline that is accessing the artifacts. `source.build.commit` - the commit of the source pipeline that is accessing the artifacts. `source.build.message` - the commit message of the source pipeline that is accessing the artifacts.
`target.build.*`	`Build`	The build in the target pipeline that the artifacts are being accessed from. This includes all the variables available for a build. Example variables available: `target.build.branch` - the branch of the target pipeline that the artifacts are being accessed from. `target.build.commit` - the commit of the target pipeline that the artifacts are being accessed from. `target.build.message` - the commit message of the target pipeline that the artifacts are being accessed from.
`source.request.query`	`String`	The query used to search for artifacts in the target build. See Searching artifacts for more information on the query syntax.

source.build.*

Build

The build in the source pipeline that is accessing the artifacts. This includes all the variables available for a build.

Example variables available:

source.build.branch - the branch of the source pipeline that is accessing the artifacts.
source.build.commit - the commit of the source pipeline that is accessing the artifacts.
source.build.message - the commit message of the source pipeline that is accessing the artifacts.

target.build.*

Build

The build in the target pipeline that the artifacts are being accessed from. This includes all the variables available for a build.

Example variables available:

target.build.branch - the branch of the target pipeline that the artifacts are being accessed from.
target.build.commit - the commit of the target pipeline that the artifacts are being accessed from.
target.build.message - the commit message of the target pipeline that the artifacts are being accessed from.

source.request.query String The query used to search for artifacts in the target build. See Searching artifacts for more information on the query syntax.

Conditions are shown in error messages when access is denied.

Learn more about creating rules in Manage rules.

Example use case: sharing assets between clusters

Artifacts are not accessible between pipelines across different clusters. For example, a deployment pipeline in cluster B cannot ordinarily access artifacts uploaded by a CI pipeline in cluster A.

However, a pipeline.artifacts_read.pipeline rule can be used to override this restriction. For example, assets uploaded as artifacts by the CI pipeline would now be accessible to the deployment pipeline via the buildkite-agent artifact download --build xxx command.