Skip to main content
POST
Generate a CI skip plan for a Buildkite pipeline

Authorizations

Authorization
string
header
required

An API key, sent as Authorization: Bearer <key>. An organization admin creates one in the Trunk app under Settings → Developer → API Keys and chooses the permissions it holds. A key with none can read merge queues but change nothing in them. Permissions cover merge queues and test-result uploads, including the quarantine lookups a CI run makes before it uploads; any key can call the other Flaky Tests and Dynamic CI endpoints, including their writes.

Body

application/json
repo
object
required
commitSha
string
required

The commit being built — BUILDKITE_COMMIT.

Example:

"9f2c1b7c2b4c9d1e0a3f5b6c7d8e9f0a1b2c3d4e"

baseSha
string | null
required

The commit to diff against. Null for a non-pull-request event, leaving diff-derived signals without evidence.

Example:

"1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d"

branch
string
required
Example:

"feature/widget-cache"

prNumber
integer | null
required

Null for a non-pull-request event.

Example:

4213

runId
string
required

BUILDKITE_BUILD_NUMBER, recorded so the plan can later be scored against the build's outcome. Not BUILDKITE_BUILD_ID: a build Trunk started before queue is matched by its number.

Example:

"4821"

runAttempt
integer
required

Which attempt this is, counting from 1. An agent's BUILDKITE_RETRY_COUNT counts from 0, so send it plus one.

Example:

1

buildkiteOrganizationSlug
string
required

BUILDKITE_ORGANIZATION_SLUG on an agent.

Required string length: 1 - 200
Example:

"acme"

buildkitePipelineSlug
string
required

BUILDKITE_PIPELINE_SLUG on an agent.

Required string length: 1 - 200
Example:

"widgets-pr"

triggeringActor
string

BUILDKITE_BUILD_CREATOR.

Example:

"octocat"

eventName
string

What triggered the build — BUILDKITE_SOURCE.

Example:

"webhook"

prLabels
string[]
deprecated

Ignored. Trunk reads the pull request's labels itself when the run asks for a plan. While the repository is in Learning mode, a pull request carrying a label on the repository's managed allow list (matched case-insensitively) is gated as if Dynamic CI were enabled. Accepted so that older clients still validate.

Maximum array length: 1000
Maximum string length: 256
Example:
jobKeys
string[]

The step key: values to decide — what Trunk ingests from buildkite.step.key. Empty means every keyed step in the pipeline — the usual call.

Maximum array length: 1000
Example:
ignoreSignals
enum<string>[]

Signals to drop from the tally. An unrecognized identifier is rejected, so a typo surfaces.

Maximum array length: 64

Which independent signal produced a contribution to a job's verdict. These identifiers are also what ignoreSignals accepts.

Available options:
estimated-cost,
previous-result-on-pr,
historical-pass-rate,
diff-driven-volatility,
force-override,
merge-failure,
mid-pr-stack,
required-check,
merge-queue-is-required,
paths-filter,
draft-pull-request,
impact-reach
Example:
changedFiles
object

The files changed between base and commitSha, diffed from their merge base (base...commitSha). No file contents. Omit it if you cannot compute the diff; never send an empty list in its place. An empty list says nothing changed, which is the strongest evidence to skip. When it is absent, Trunk fetches the diff through your GitHub App installation.

impacts
object[]

How much of the codebase the change affects, by each measure your own build or dependency tool computes, one entry per source. Jobs with the impact reach signal turned on always run a change that affects everything, lean toward running a broad change and lean slightly toward skipping a narrow one. Omit it when your tool computed nothing; sending nothing leaves every verdict as it is.

Maximum array length: 8
matrixBlocks
object

Each keyed matrix step's matrix: block, by step key, as buildkite-agent pipeline upload --dry-run renders it with environment variables resolved. Matrix steps are pruned per variation only when their block is sent; a step left out is decided as a whole. Send at most 64 KiB of blocks; Trunk ignores a larger map.

Example:
rbqDispatchId
string<uuid>

Set by Trunk's Run Before Queue on a build it created (TRUNK_RBQ_DISPATCH_ID). Send it unchanged when the variable is present.

Example:

"3f9d2c1e-7a4b-4e8f-9c2d-5b6a7e8f9a0b"

Response

The plan

jobs
object[]
required

One verdict per job. A job absent from this list must be run — the documented fail-safe, and how an unrecognized job, a CI job experiment branch, and a not-yet-enabled organization are all reported.

Maximum array length: 1000
notice
object

Why this plan has the shape it does. Absent unless every job runs for a reason jobs cannot express: a not-yet-enabled organization or repository, a CI job experiment branch (trunk-runners/experiments/), an engine outage, or a workflow Trunk has not enumerated — all indistinguishable otherwise, and all arriving as an empty jobs when you request a whole workflow. REPO_IN_SHADOW_MODE is the exception: the plan is fully populated and each summary is the recommendation the job would have received, but nothing is allowed to skip.