Skip to main content

How it works

A filter job at the top of your workflow runs the trunk-io/dynamic-ci action. The action asks Trunk which jobs this change needs, and writes one output per job. The outputs of the Dynamic CI step will store the verdict for each job specified. By listing a job in the list you are asking Dynamic CI to weigh in and attempt to manage that job.

If Dynamic CI determines a job should be skipped it will set the output variable named after the job to 'false'.At each job level you will need to add an if: clause to read that matching variable.
If Trunk is offline, the token is missing, or a job has no verdict yet, the output will be empty and the job will run. This allows Dynamic CI to “fail open” so you will not inadvertently skip jobs.

Workflow Example

This workflow gates two jobs. Note the job ids are the critical matched. values in this flow

Guidance for gating a job correctly

1

Use the job key, not the display name

Outputs are named by the key under jobs: In the example above playwright-tests ad unit-tests are the job ids.Re-export each gated job’s output from the filter job’s outputs:, under the same key. The action sets its outputs at runtime, so GitHub cannot pass them on unless you list them there.
2

Export the verdict for each job you want to dynamically manage in the outputs section of the Dynamic CI job

3

List the filter job in needs

Each managed job has should specify needs: [dynamic-ci-filter]. This ensures the dynamic ci verdict will be available to assess before the job ever spins up.
4

Start the condition with !cancelled()

By default GitHub skips a job when a job it needs failed or was skipped. Without !cancelled(), a failed filter job (a bad token, an outage) skips every gated job, and nothing is tested.
5

Compare with != 'false' on the output of the matching job

Join other conditions with &&
When your workflow files are updated and start calling into Dynamic CI a background linter will run to verify the format of your yaml file and call out problems.

Check your setup

  1. Open a pull request. The Dynamic CI’s verdict will be reported on each pull request under the dynamic ci tab. Additionally you can see all decisions made by the system in the Dynamic CI page.
  2. Your repository starts in Learning mode, which records verdicts but will not actively skip anything. Once the recommendations look right you can turn on enforcement.

Matrix jobs

A matrix job runs or skips as a whole unless you decide it by variation. Once you have, make the two changes below. They need trunk-io/dynamic-ci v0.1.8 or later; @v1 picks it up.

Require one check per job

A skipped variation never reports a status. If branch protection requires each variation’s check, such as Test (macos-14), a pull request that skips it waits forever on Expected — Waiting for status to be reported. Add one job that always runs after the matrix and passes when the matrix passed or was skipped, and make it the required check in place of the per-variation checks. Don’t gate this job with Dynamic CI.

Read the variations to run

For an opted-in job, the action sets one more output, which leaves the skipped variations out of the matrix. Re-export it from the Dynamic CI job’s outputs: beside the job’s own output, and read it in the matrix. Which output depends on how the matrix is written. When nothing is skipped, the output is empty and the || fallback keeps your own matrix.
For a matrix written as axes, read <job>-exclude as its exclude:
GitHub takes a single exclude value. If the matrix already excludes some combinations, move them into the fallback as JSON. Trunk keeps them in every list it sends:

Check that it works

Once a pull request skips some variations, the Dynamic CI step’s log names each group and its decision:
A pull request that edits the workflow file itself can run every variation, so check on one that changes something else.