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.

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.

Note: 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_uuid": "pipeline-uuid",
    "target_pipeline_uuid": "pipeline-uuid"
  }
}

where:

source_pipeline_uuid is the UUID of the pipeline that's allowed to trigger another pipeline.
target_pipeline_uuid is the UUID of the pipeline that can be triggered by the source_pipeline_uuid pipeline.

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_uuid": "pipeline-uuid",
    "target_pipeline_uuid": "pipeline-uuid"
  }
}

where:

source_pipeline_uuid is the UUID of the pipeline that's allowed to access the artifacts from another pipeline.
target_pipeline_uuid is the UUID of the pipeline whose artifacts can be accessed by jobs in the source_pipeline_uuid pipeline.

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.