GitHub Action that recommends which CI jobs to run for the current diff, using your organization's own CI history. It runs before your work, asks the Trunk recommendation service for a per-job verdict, and emits those verdicts as job outputs you gate on.
It is a near drop-in replacement for path-based filtering: instead of hand-written path globs, verdicts come from signals measured on your repository — historical pass rates, whether the job already passed on this commit, how volatile the changed files are, cost, and more.
Important
This is a beta product. Recommendation quality is still improving, the set of signals behind a verdict is still changing, and this action's inputs and outputs may change between releases. Pin a specific tag rather than a moving major version if you need stability, and read the release notes before upgrading.
A recommendation can be wrong, so the jobs that gate a merge still need to run somewhere. If you use Trunk's Merge Queue or GitHub's native merge queue that is handled for you — the service never skips a job on a merge-queue branch, so you do not need to special-case the queue in your workflow. See Merge queues for what is and isn't covered.
One upstream job asks for verdicts for the whole workflow, and every downstream job gates on its outputs. This captures the most savings, because a skipped job never boots a runner.
jobs:
dynamic-ci-filter:
name: Dynamic CI Filter
runs-on: ubuntu-latest
timeout-minutes: 5
# Only ask on pull requests; on other events the gate is skipped and, with no
# outputs to compare against, every job below runs.
if: github.event_name == 'pull_request'
# Per-job outputs are set at runtime, so they must be re-exported here by name.
outputs:
unit-tests: ${{ steps.ci-filter.outputs.unit-tests }}
integration-tests: ${{ steps.ci-filter.outputs.integration-tests }}
steps:
# Check out first, with full history, so the action can read the changed files.
- uses: actions/checkout@v4
with:
fetch-depth: 0
filter: blob:none
- name: Run Dynamic CI Filter
id: ci-filter
uses: trunk-io/dynamic-ci@v1
with:
token: ${{ secrets.TRUNK_API_TOKEN }}
unit-tests:
name: Unit Tests
runs-on: ubuntu-latest
needs: [dynamic-ci-filter]
# Always compare against 'false', never 'true' — see "Outputs" below.
# No merge-queue escape hatch needed: see "Merge queues".
if: >-
!cancelled() &&
needs.dynamic-ci-filter.outputs.unit-tests != 'false'
steps:
- run: make test| Input | Required | Description |
|---|---|---|
token |
yes | Trunk organization API token. Find it at app.trunk.io → Settings → Manage Organization → Organization API Token. |
job-keys |
no | A job key, or comma-separated list of job keys, to scope the recommendation to. Leave unset to get a verdict for every job. |
ignore-signals |
no | Comma-separated signal identifiers to exclude from the recommendation. Forwarded to the service as given; an identifier this action version does not know is warned about and still sent. |
impacts |
no | A JSON list of how much of the codebase the change affects, one entry per measure. See Impact reach. |
matrices |
no | A JSON object of job key to the rows a planner job built for that job's matrix. See A matrix built by a planner job. |
enable-annotation |
no | Post the recommendation to the run — its annotation list and the job summary. Defaults to false; the step's logs are written either way. |
Jobs are addressed by their key — what the job is written as under jobs: in the
workflow file, and what github.job reports — not by the name: it displays under. A
display name changes with a job's matrix values; the key does not, which is what makes
it safe to put in an if:.
One output per job, whose value is the string 'true' (run) or 'false' (skip).
A matrix job decided by matrix variation can also get <job>-exclude, <job>-matrix and
<job>-include. See Skipping single matrix variations.
The output is named for the job key verbatim. GitHub already constrains a jobs: key to
what an expression can dereference, so a job written as unit-tests is read back as
steps.ci-filter.outputs.unit-tests with no transformation to work out.
Run inside a reusable workflow, the action decides the jobs of the workflow that calls it,
so a job it calls is keyed <caller>/<job>. Its output is also set under <job>, which is
what a gate inside the called workflow reads, unless another job has that name.
When several jobs call that workflow, github-token needs the checks: read permission.
Always write != 'false', never == 'true'. A job with no verdict — a service
outage, a job the service has never seen, a job whose key it has not resolved yet —
emits no output at all, and != 'false' correctly runs it. Writing == 'true' would silently
skip your entire test suite the first time something goes wrong.
The action is built so that it can never block your CI:
- A transport error, non-2xx response, malformed response, or a request exceeding the
latency budget (30s by default) all leave every job's output unset, which your
!= 'false'conditionals read as "run". - An empty
tokensets every job injob-keysto'true'and says why. On a pull request from a fork that is expected: GitHub gives a fork's pull request no repository secrets, so Dynamic CI does not decide jobs for fork pull requests and every job runs. - Unexpected failures are caught too, and emit no outputs at all, which your
!= 'false'conditionals read as "run". - It never calls
core.setFailed, so the step itself always succeeds. Failing the step would defeat the purpose.
Every fail-open is logged with the reason, so you can tell a real skip from a degraded
one. With enable-annotation: true it is also a warning annotation on the run and a
job summary.
Trunk can answer successfully and still have nothing to recommend — because Dynamic CI is not enabled for your organization, because the branch is a merge-queue branch, because the engine was unavailable, or because Trunk has not yet enumerated the jobs in this workflow. Every job runs in all four cases, which is the fail-safe working as intended.
When that happens the response carries a notice, and the action renders it in the
logs (and, with enable-annotation: true, as a warning annotation) — for example:
Every job will run: Dynamic CI is not enabled for this organization. Contact Trunk to turn it on.
[ORG_NOT_ENABLED]
A notice covers every expected cause, so a plan that arrives empty without one means something went wrong that Trunk could not name. The action says so and points you at slack.trunk.io rather than printing an empty heading.
A merge queue validates the exact commit that is about to land, so skipping a job there
could merge untested code. The service therefore never skips a job on a merge-queue
branch: a request whose branch starts with trunk-merge/ (Trunk Merge Queue) or
gh-readonly-queue/ (GitHub's native merge queue) short-circuits to a run-everything
verdict before any recommendation work happens. It is a branch-name check rather than a
heuristic, so it is both deterministic and fast.
You therefore do not need to gate either queue yourself, and in particular you do not need
github.event_name != 'pull_request' or github.event_name == 'merge_group' in your
conditions. The event name is the wrong thing to test in both directions: with draft
merge-queue pull requests enabled, Trunk queue batches arrive as pull_request events on
trunk-merge/* branches, so the event name cannot tell them apart from real PRs; and
GitHub's queue runs merge_group events on gh-readonly-queue/* branches, which the
branch check already covers. Use the action the same way everywhere and let the branch
check do the work.
On a merge-queue branch the response carries no verdicts, so no outputs are set at all —
which your != 'false' conditions already read as "run". This is one more reason never to
write == 'true'.
Other merge queues are not covered. The check matches the trunk-merge/ and
gh-readonly-queue/ prefixes only, so a third-party queue that validates on some other
branch prefix is treated like any other request — gate that one yourself:
if: >-
!cancelled() &&
(startsWith(github.ref_name, 'my-queue/') ||
needs.dynamic-ci-filter.outputs.unit-tests != 'false')You may wish to use another paths filter mechanism to deterministically reduce what runs in the merge queue. If you have feedback on the filtering mechanism in merge queues, reach out to us on Slack.
Each verdict is a combination of independent signals, and each signal's contribution
is shown in the logs. Pass any of these to ignore-signals to drop it from the tally:
| Signal | What it looks at |
|---|---|
estimated-cost |
What the job costs to run. |
previous-result-on-pr |
Whether this job already ran on this PR, and how it did. |
historical-pass-rate |
How often this job has failed historically. |
diff-driven-volatility |
How often changes to these files have broken this job. |
force-override |
An explicit user override forcing the job to run. |
merge-failure |
Whether this job failed on the PR's most recent merge-queue run. |
mid-pr-stack |
Whether another open PR is stacked on top of this one. |
required-check |
Whether the PR's base branch requires this job to merge. |
impact-reach |
How much of the codebase the change affects (see below). |
The identifiers this action version knows about are the SignalType enum in
src/schema/dynamic-ci-contract.json, which
src/compat.ts reads as SIGNAL_TYPES. Signals are added and retired while
this is in beta, and the service ships them before that vendored list catches up, so
neither side treats an unfamiliar identifier as an error:
- A signal the service returns that this version does not know is reported in the logs like any other, and the verdict it belongs to is honored.
- An
ignore-signalsidentifier this version does not know is warned about and forwarded anyway — so a typo has no effect, rather than taking the gate down.
Check SIGNAL_TYPES for the release you have pinned to see what this version can
describe, but read the step's logs for what actually voted.
Send how much of the codebase the change affects, by each measure your own build or dependency tool computes. On jobs where Trunk's impact reach signal is on, Dynamic CI always runs a change that affects everything, leans toward running a broad change and leans slightly toward skipping a narrow one. Trunk sets each job's limit per source. Sending nothing leaves every verdict as it is.
- id: affected
run: echo "count=$(npx nx show projects --affected --base=origin/main | wc -l)" >> "$GITHUB_OUTPUT"
- uses: trunk-io/dynamic-ci@v1
with:
token: ${{ secrets.TRUNK_TOKEN }}
impacts: |
[{ "source": "nx-affected-projects", "count": ${{ steps.affected.outputs.count }} }]Each entry has:
source: the measure, such asnx-affected-projectsortest-files. Lowercase letters, digits,.,_and-, at most 64 characters. Send each source once, and keep its measure the same on every run.count: how many units the change affects (packages, targets, test files or tests). Required unlessallistrue. Send0when nothing is affected.all:truewhen the tool says the change affects everything, or could not work out what is affected. Never send a large count in its place.
Leave a source out when your tool did not compute it. At most 8 entries. An unreadable entry is dropped with a warning and the others are sent; input that is not a JSON list sends no impacts. The plan is still requested.
| Variable | Default | Description |
|---|---|---|
TRUNK_PUBLIC_API_ADDRESS |
https://api.trunk.io |
Trunk API base address (host only). The recommendation path is appended to it. |
TRUNK_DYNAMIC_CI_TIMEOUT_MS |
30000 |
Request timeout, which is also the fail-open latency budget. Invalid values fall back to 30000. |
By default Trunk decides a matrix job as a whole: every matrix variation runs or every one skips. When
the job is set in Dynamic CI's job settings to be decided by matrix variation (for example
by os), Trunk decides each variation on its own history, and the action sets one more
output for the job that leaves the skipped variations out of the matrix. Wire the output that
fits how the matrix is written. Nothing is set when no variation is skipped, so the ||
fallback keeps your own matrix.
The action's log lists such a job's variations instead of its signals, one line per group decided together, named by the keys the job is decided by (other matrix keys, such as a shard index, are left out):
test: RUN — Runs 2 of 4 matrix variations (os=ubuntu-latest ×2); skips 2 (os=macos-14 ×2).
- [RUN] os=ubuntu-latest ×2: The job should run because …
- [SKIP] os=macos-14 ×2: The job should skip because …
A matrix declared with axes reads <job>-exclude as its exclude. Move any
exclude entries you already have into the fallback, because GitHub takes one
exclude value:
dynamic-ci-filter:
outputs:
test: ${{ steps.ci-filter.outputs.test }}
test-exclude: ${{ steps.ci-filter.outputs.test-exclude }}
# ...
test:
needs: [dynamic-ci-filter]
if: ${{ !cancelled() && needs.dynamic-ci-filter.outputs.test != 'false' }}
strategy:
matrix:
os: [ubuntu-latest, macos-14]
node: [18, 20]
exclude: ${{ fromJSON(needs.dynamic-ci-filter.outputs.test-exclude || '[{"os":"macos-14","node":18}]') }}A matrix written as a list of rows cannot use exclude: GitHub applies exclude
before include. Write the rows as a JSON literal and read <job>-matrix in its place.
The output holds the rows that run, each exactly as you wrote it, so job names do not
change:
unit-tests:
needs: [dynamic-ci-filter]
if: ${{ !cancelled() && needs.dynamic-ci-filter.outputs.unit-tests != 'false' }}
strategy:
matrix: ${{ fromJSON(needs.dynamic-ci-filter.outputs.unit-tests-matrix || '{"include":[{"suite":"packages"},{"suite":"apps"}]}') }}<job>-include holds the same rows as a bare array, for a matrix that reads them at
strategy.matrix.include. A wrong output in the wrong place makes GitHub reject the
matrix, which shows as a failed job the first time a variation is skipped.
When a planner job builds the rows at run time (fromJSON), the workflow file does not
have them, so give them to the filter in its matrices input. The filter then runs after
the planner, and the job reads the rows that run from <job>-include, or <job>-matrix
when it reads a whole matrix object:
dynamic-ci-filter:
needs: [plan]
outputs:
tests: ${{ steps.f.outputs.tests }}
tests-include: ${{ steps.f.outputs.tests-include }}
steps:
- id: f
continue-on-error: true
uses: trunk-io/dynamic-ci@v1
with:
token: ${{ secrets.TRUNK_API_TOKEN }}
matrices: >-
{"tests": ${{ needs.plan.outputs.rows || '[]' }}}
tests:
needs: [plan, dynamic-ci-filter]
if: ${{ !cancelled() && needs.dynamic-ci-filter.outputs.tests != 'false' }}
strategy:
matrix:
include: ${{ fromJSON(needs.dynamic-ci-filter.outputs.tests-include || needs.plan.outputs.rows) }}- Pass the planner's output unchanged. The filter sends each job's rows as written, and the output keeps the rows that run in the same text, so job names do not change.
- The rows must be the job's whole matrix: an expression for all of
matrix:, or forinclude:with no matrix variables (such asos: [linux, macos]) beside it. A job with variables beside the expression runs or skips as a whole, because a row can then add to a variable's job instead of making its own. - The fields that name a variation are set in Dynamic CI's job settings, not here. A field that changes on every run, such as a shard number, gives a new variation on every run.
- The filter sends at most 64 jobs, 64 KiB of rows for each job and 256 KiB in all. A job over these limits runs or skips as a whole, and the step logs a warning.
GitHub evaluates a job's if: before it expands the matrix, so a matrix job that Dynamic
CI skips emits a single check run under the unexpanded name:
Test for ${{ matrix.platform.target }}
Per-leg contexts like Test for x86_64-apple-darwin then never report, and a pull request
whose branch protection requires them waits on "Expected — Waiting for status to be
reported" indefinitely. Wildcards are no help: required contexts are exact-match
strings on every plan. Non-matrix jobs are unaffected — a skipped job reports a skipped
conclusion, which branch protection accepts as satisfied.
Four ways to resolve it:
| Option | How it works | Trade-off |
|---|---|---|
| Fan-in job (recommended) | Add one if: always() job that needs the gated jobs and passes when each finished success or skipped. Require its name in place of the leg names. |
Aggregates per job, so it cannot require a subset of legs. Never gate this job with Dynamic CI — a gate that can be skipped cannot report. |
| Require the workflow | GitHub's "Require workflows to pass before merging" ruleset rule keys on the workflow file path, and a run whose jobs all skip still concludes successfully. | GitHub Enterprise Cloud only. Requires the workflow as a whole, so jobs you had left out of the required set start blocking merges. |
| Leave the job ungated | Omit the matrix job from the filter's outputs: and give it no if:. Its per-leg contexts keep reporting exactly as they do today. |
No savings on that job. Everything else in the workflow can still be gated. |
| In-step gating (discouraged) | Move the verdict out of the job's if: and into each step's if:, so every leg still boots and still reports its context. |
Spends the runner anyway, and reports success without doing the work — feeding historical-pass-rate and previous-result-on-pr a pass that never happened. |
Prefer the fan-in job: it costs one cheap runner and keeps the pass-rate signals honest.
This action is for GitHub Actions. The Buildkite equivalent is a plugin, and it lives in its own repository: trunk-io/dynamic-ci-buildkite-plugin.
See CONTRIBUTING.md.