> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trunk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# BuildKite

> Add the Dynamic CI plugin to a Buildkite pipeline.

**1. Configure Secrets in BuildKite:  [Create a Trunk API Key](https://docs.trunk.io/api/authentication) 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](https://docs.trunk.io/setup/integrations/buildkite.md)**

**3. Paste a BuildKite API token into [Settings → Organization → Buildkite](https://app.trunk.io/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](https://docs.trunk.io/ci/dynamic-ci/configuration/mode.md).

```yaml theme={"system"}
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](https://github.com/trunk-io/dynamic-ci-buildkite-plugin/releases), 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](https://docs.trunk.io/ci/dynamic-ci/configuration/matrices.md).

## 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`:

```yaml theme={"system"}
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](https://app.trunk.io/dynamic-ci) →
your repository → **Configuration**.

> [accordion] Run it beside your pipeline (dry run)
>
> 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.
>
> ```yaml theme={"system"}
> - 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. Move to
> the upload step before you turn on enforcement.

> [accordion] 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.

> [accordion] 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:
>
> ```bash theme={"system"}
> 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.

> [accordion] 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). |

## Matrix steps

A `matrix:` step runs or skips as a whole unless you
[decide it by variation](https://docs.trunk.io/ci/dynamic-ci/configuration/matrices.md). 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](https://docs.trunk.io/ci/dynamic-ci/force-run.md#trunk-web-app)
in the Trunk web app; the browser extension's controls are for GitHub Actions.

## Next

[Turn on enforcement](https://docs.trunk.io/ci/dynamic-ci/getting-started.md). To stop using Dynamic CI,
remove the plugin or set the repository back to **Learning**. For merge-queue
behaviour, see [Merge queues](https://docs.trunk.io/ci/dynamic-ci/merge-queue.md).
