Skip to content

About

Dynamically run actions based on historical workflow information and pull request risk

Resources

Contributing

Stars

1 star

Watchers

1 watching

Forks

Repository files navigation

Trunk Dynamic CI Filter

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.

Usage

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

Inputs

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:.

Outputs

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.

Failing open

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 token sets every job in job-keys to '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.

When Trunk returns no recommendations

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.

Merge queues

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.

Signals

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-signals identifier 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.

Impact reach

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 as nx-affected-projects or test-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 unless all is true. Send 0 when nothing is affected.
  • all: true when 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.

Environment variables

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.

Matrices

Skipping single matrix variations

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.

A matrix built by a planner job

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 for include: with no matrix variables (such as os: [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.

Matrix legs as required checks

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.

Buildkite

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.

Contributing

See CONTRIBUTING.md.

About

Dynamically run actions based on historical workflow information and pull request risk

Resources

Contributing

Stars

1 star

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages