Set up Trunk Dynamic CI for Buildkite

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

The key doesn’t need any permissions.

Configure BuildKite to export CI data to Trunk: connecting BuildKite's OTEL data allows us to learn the behavior of your CI jobs

Paste a BuildKite API token with the read_builds and read_organizations scopes into Settings → Organization → Buildkite. Use a token from a dedicated BuildKite user.

Give your steps keys

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

Start with a dry run

Add this step to each pull request pipeline that runs your tests and checks. Trunk records verdicts, and your pipeline is unchanged.

- label: ":trunk: Dynamic CI (learning, no-op)"
  timeout_in_minutes: 5
  secrets:
    - TRUNK_API_TOKEN
  # Replace .buildkite/pr-checks.yml with your pipeline file, or pipe your
  # pipeline generator's output into trunk-dynamic-ci-filter instead.
  command: trunk-dynamic-ci-filter < .buildkite/pr-checks.yml > /dev/null
  plugins:
    - trunk-io/dynamic-ci#v0.1.5:
        token-env: TRUNK_API_TOKEN

Use the same if: and agents: as your other pull request steps.

Add the plugin to your upload step

When you are ready to skip steps, pipe your pipeline through the filter on its way to upload:

steps:
  - label: ":pipeline: upload"
    secrets:
      - TRUNK_API_TOKEN
    command: |
      cat .buildkite/pipeline.yml \
        | trunk-dynamic-ci-filter \
        | buildkite-agent pipeline upload
    plugins:
      - trunk-io/dynamic-ci#v0.1.5:
          token-env: TRUNK_API_TOKEN

Pin an exact release, v0.1.3 or later.
Don’t pass --no-interpolation to buildkite-agent pipeline upload.
trigger: steps are never skipped. Matrix and parallelism: legs skip together.

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:

plugins:
  - trunk-io/dynamic-ci#v0.1.5:
      token-env: TRUNK_API_TOKEN
      exclude-keys: deploy-master,publish-release

Or set them to Always run in Dynamic CI → your repository → Configuration.

Pipelines with no upload step (step mode)

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.

Send your build tool's impact (v0.1.8 or later)

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:

export BUILDKITE_PLUGIN_DYNAMIC_CI_IMPACTS='[{"source":"tainted-packages","count":734}]'

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.

All options

Option	Default	Description
`mode`	`filter`	`filter` for your upload pipe, `step` for the step the plugin is on.
`token-env`	`TRUNK_TOKEN`	The environment variable holding your Trunk API key.
`only-keys`	unset	Comma-separated step keys to consider. Every other step runs.
`exclude-keys`	unset	Comma-separated step keys to never skip. Wins over `only-keys`.
`debug`	`false`	Print the requested keys, the request and the plan to the build log.
`ignore-signals`	unset	Comma-separated signal identifiers to leave out. Ask us for the list.
`impacts`	unset	A list of `source`, `count` and `all` known when the pipeline is written. For a count computed during the build, use `BUILDKITE_PLUGIN_DYNAMIC_CI_IMPACTS` (above).

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. Force overrides from the browser extension are not available for Buildkite yet.

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.

Overview

CI providers

Configuration

Reference

BuildKite

Give your steps keys

Start with a dry run

Add the plugin to your upload step

Mark steps that must never be skipped

Troubleshooting

Next

​Give your steps keys

​Start with a dry run

​Add the plugin to your upload step

​Mark steps that must never be skipped

​Troubleshooting

​Next

Give your steps keys

Start with a dry run

Add the plugin to your upload step

Mark steps that must never be skipped

Troubleshooting

Next