Skip to main content
1

Configure Secrets in BuildKite: Create a Trunk API Key and add it to BuildKite's secret store named TRUNK_API_TOKEN

When you create it, select the Generate Dynamic CI plans permission. A new key has no permissions, and without this one Trunk refuses every plan request and every job runs.
2

Setup OpenTelemetry Export from BuildKite: Provides span data to the Dynamic CI system so we can learn about your pipelines and jobs. Configure BuildKite to export CI data to Trunk

3

Paste a BuildKite API token into Settings → Organization → Buildkite. Use a token from a dedicated BuildKite user.

The token needs these scopes:
  • read_builds
  • write_builds
  • read_pipelines
  • read_organizations
The token’s user needs Build & Read access on your pipelines.

Give your steps keys

Add a key: to every step you might want skipped. A step without one always runs.

Add the plugin to your upload step

Pipe your pipeline through the filter on its way to upload. Your repository starts in Learning mode, so Trunk records a verdict for every step and skips nothing until you turn on enforcement.
  • Pin an exact release, v0.1.3 or later.
  • Don’t pass --no-interpolation to buildkite-agent pipeline upload.
  • trigger: steps are never skipped. A parallelism: step runs or skips as a whole. So does a matrix: step, unless you decide it by variation.

Mark steps that must never be skipped

Trunk can’t tell which Buildkite steps are required to merge. Before you turn on enforcement, list them in exclude-keys:
Or set them to Always run in Dynamic CI → your repository → Configuration.
To try Dynamic CI without touching your upload step, add this step to each pull request pipeline that runs your tests and checks instead. Trunk records verdicts, and your pipeline is unchanged.
Use the same if: and agents: as your other pull request steps. Move to the upload step before you turn on enforcement.
If your pipeline lives in Buildkite’s settings editor, put the plugin on the step itself with mode: step. The step needs a key:. It saves less, because the agent has already started, and a skipped step reports as passed.
If your build tool measures how much of the codebase a change affects, such as a count of affected packages, send it so Trunk runs broad changes. Export it as a JSON list in the upload step’s command, before the filter runs:
  • source: your name for the measure (lowercase letters, digits, ., _, -). Keep it the same on every build.
  • count: a whole number. Send 0 when nothing is affected.
  • all: true in place of count when everything is affected.
Leave the variable unset when your tool computed nothing. A bad entry is dropped with a warning, and the build continues. Ask us to turn the signal on and set each step’s limit.

Matrix steps

A matrix: step runs or skips as a whole unless you decide it by variation. Once you have, nothing in your pipeline changes beyond the plugin, which must be v0.1.9 or later. When Trunk skips some variations of a step, the plugin leaves them out of the step it uploads, and the upload step’s log counts them.
  • A matrix with no dimension names (matrix: [amd64, arm64]): the skipped values are removed from the list.
  • A matrix with named dimensions (setup: {os: [...], arch: [...]}): a matrix.adjustments entry with skip: is added for each skipped variation. Buildkite allows 12 adjustments per step, counting your own; when a build would need more, every variation of that step runs.
Give each dimension a name: a setup whose dimension is named "" is always decided as a whole. The plugin sends your matrix values to Trunk with environment variables filled in, so don’t put a secret in a matrix value.

Troubleshooting

Set debug: true to print what the plugin asked for and the plan it got back.
  • Nothing is skipped. Check the repository is Enforced, the steps have a key:, and Trunk has a couple of days of builds for them.
  • The plan request returns 404. The pipeline’s remote doesn’t match a repository in your Trunk organization with CI data.
  • baseSha is null on a pull request build. Fetch the target branch before the upload step.
Builds without a pull request, such as pushes to your default branch, can be skipped. To force a step, use Force Run in the Trunk web app; the browser extension’s controls are for GitHub Actions.

Next

Turn on enforcement. To stop using Dynamic CI, remove the plugin or set the repository back to Learning. For merge-queue behaviour, see Merge queues.