Skip to main content
POST
Generate a CI skip plan

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 (github.sha).

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

github.run_id, recorded so the plan can later be scored against the run's outcome.

Example:

"18342998211"

runAttempt
integer
required

github.run_attempt, which disambiguates re-runs.

Example:

1

workflowPath
string
required

From github.workflow_ref; identifies the workflow whose jobs are in scope.

Example:

".github/workflows/ci.yaml"

triggeringActor
string

github.triggering_actor.

Example:

"octocat"

eventName
string

github.event_name.

Example:

"pull_request"

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 jobs: keys to decide. Empty means every keyed job in the workflow — 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
workflowFileSha
string

The git blob sha of the workflow file at commitSha (git rev-parse <commitSha>:<workflowPath>). Matrix jobs are pruned only against the parsed version of exactly this file; without it, a matrix job is decided as a whole.

Pattern: ^[0-9a-f]{40}([0-9a-f]{24})?$
Example:

"51d537a714c0f1c8a4e92b13d5f0e6a7c2b9d8e1"

filterJobKey
string

GITHUB_JOB: the key of the job this request is sent from, in the workflow file that defines it.

Required string length: 1 - 1024
Example:

"dynamic-ci"

jobWorkflowRef
string

job.workflow_ref: the workflow file that defines the job this request is sent from. Inside a reusable workflow it names the called file, where workflowPath names the calling one. Omit it when GitHub leaves it empty.

Required string length: 1 - 1024
Example:

"octo-org/octo-repo/.github/workflows/reusable-tests.yaml@refs/heads/main"

jobWorkflowSha
string

job.workflow_sha: the commit that workflow file was read from. Omit it when GitHub leaves it empty.

Pattern: ^[0-9a-f]{40}([0-9a-f]{24})?$
Example:

"9fd89fd49ccc84094552b62860aa14089c88c4a4"

checkRunId
integer

job.check_run_id: the check run of the job this request is sent from. Inside a reusable workflow it tells apart the jobs that call one file. Omit it when GitHub leaves it empty.

Example:

135132011429

checkRunName
string

The name GitHub gave the check run checkRunId names (<calling job> / <job> inside a reusable workflow). Inside a reusable workflow called from several jobs it tells them apart. Omit it when the check run could not be read.

Required string length: 1 - 1024
Example:

"Lint Suite / dynamic-ci"

matrixRows
object

For matrix jobs whose rows a planner job builds at run time (fromJSON): each job's rows array, by job key, as the exact JSON text the planner emitted. Send the text unchanged; Trunk returns the rows it keeps in the same text. A job is pruned per variation only when its rows are sent and they are its whole matrix. Send at most 64 jobs, 64 KiB and 256 rows per job, and 256 KiB in all; a job over its limits is decided as a whole.

Example:
matrixRowsOmitted
string[]

Job keys whose rows you left out of matrixRows for size. Informational: those jobs are decided as a whole.

Maximum array length: 64
Example:

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.