> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trunk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Actions

> Adding Dynamic CI to your existing GitHub Actions workflows

## 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

```yaml theme={"system"}
name: CI

on:
  pull_request: {}

jobs:
  dynamic-ci:
    name: Dynamic CI
    runs-on: ubuntu-latest
    timeout-minutes: 5
    if: github.event_name == 'pull_request'
    # One output per gated job, named by its job key.
    outputs:
      unit-tests: ${{ steps.dynamic-ci.outputs.unit-tests }}
      playwright-tests: ${{ steps.dynamic-ci.outputs.playwright-tests }}
    steps:
      - uses: actions/checkout@v7
        with:
          clean: false
      - uses: trunk-io/dynamic-ci@v1
        with:
          token: ${{ secrets.TRUNK_API_TOKEN }}

  unit-tests:
    name: Unit Tests
    runs-on: ubuntu-latest
    needs: [dynamic-ci]
    if: >-
      !cancelled() &&
      needs.dynamic-ci.outputs.unit-tests != 'false'
    steps:
      - uses: actions/checkout@v7
      - run: make test

  playwright-tests:
    name: Playwright Tests
    runs-on: ubuntu-latest
    needs: [dynamic-ci]
    if: >-
      !cancelled() &&
      needs.dynamic-ci.outputs.playwright-tests != 'false'
    steps:
      - uses: actions/checkout@v7
      - run: make test
```

## 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 \*\*

```yaml theme={"system"}
outputs:
  unit-tests: ${{ steps.dynamic-ci.outputs.unit-tests }}
  playwright-tests: ${{ steps.dynamic-ci.outputs.playwright-tests
```

\*\*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](https://app.trunk.io/dynamic-ci).
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](https://docs.trunk.io/ci/dynamic-ci/configuration/mode.md).

## Matrix jobs

A matrix job runs or skips as a whole unless you
[decide it by variation](https://docs.trunk.io/ci/dynamic-ci/configuration/matrices.md). 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.

```yaml theme={"system"}
test-pass: # make this the required check
  needs: [test]
  if: ${{ !cancelled() }}
  runs-on: ubuntu-latest
  steps:
    - run: '[[ "${{ needs.test.result }}" =~ ^(success|skipped)$ ]]'
```

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

> [tab] Axis
>
> For a matrix written as axes, read `<job>-exclude` as its `exclude`:
>
> ```yaml theme={"system"}
> jobs:
>   dynamic-ci:
>     # ...
>     outputs:
>       test: ${{ steps.dynamic-ci.outputs.test }}
>       test-exclude: ${{ steps.dynamic-ci.outputs.test-exclude }}
>
>   test:
>     needs: [dynamic-ci]
>     if: >-
>       !cancelled() &&
>       needs.dynamic-ci.outputs.test != 'false'
>     name: Test (${{ matrix.os }}, node ${{ matrix.node }})
>     strategy:
>       matrix:
>         os: [ubuntu-latest, macos-14]
>         node: [18, 20]
>         exclude: ${{ fromJSON(needs.dynamic-ci.outputs.test-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:
>
> ```yaml theme={"system"}
> exclude: ${{ fromJSON(needs.dynamic-ci.outputs.test-exclude || '[{"os":"macos-14","node":18}]') }}
> ```

> [tab] Fixed-include
>
> A matrix written as an `include:` list of rows can't use `exclude`, because
> GitHub applies `exclude` before `include`. Write the rows as a JSON literal and
> read `<job>-matrix` in its place:
>
> ```yaml theme={"system"}
> jobs:
>   dynamic-ci:
>     # ...
>     outputs:
>       unit-tests: ${{ steps.dynamic-ci.outputs.unit-tests }}
>       unit-tests-matrix: ${{ steps.dynamic-ci.outputs.unit-tests-matrix }}
>
>   unit-tests:
>     needs: [dynamic-ci]
>     if: >-
>       !cancelled() &&
>       needs.dynamic-ci.outputs.unit-tests != 'false'
>     name: Unit tests (${{ matrix.suite }})
>     strategy:
>       matrix: ${{ fromJSON(needs.dynamic-ci.outputs.unit-tests-matrix || '{"include":[{"suite":"packages"},{"suite":"apps"},{"suite":"frontend"}]}') }}
> ```
>
> The output holds the rows that run, each exactly as you wrote it, so job names
> don't change.

> [tab] Dynamic-include
>
> When an earlier job builds the matrix at run time, give its rows to the
> action's `matrices` input, so the Dynamic CI job runs after the planner. Then
> read `<job>-include` as the matrix's `include`:
>
> ```yaml theme={"system"}
> jobs:
>   dynamic-ci:
>     needs: [plan]
>     # ...
>     outputs:
>       tests: ${{ steps.dynamic-ci.outputs.tests }}
>       tests-include: ${{ steps.dynamic-ci.outputs.tests-include }}
>     steps:
>       # ...
>       - id: dynamic-ci
>         uses: trunk-io/dynamic-ci@v1
>         with:
>           token: ${{ secrets.TRUNK_API_TOKEN }}
>           matrices: >-
>             {"tests": ${{ needs.plan.outputs.rows || '[]' }}}
>
>   tests:
>     needs: [plan, dynamic-ci]
>     if: >-
>       !cancelled() &&
>       needs.dynamic-ci.outputs.tests != 'false'
>     strategy:
>       matrix:
>         include: ${{ fromJSON(needs.dynamic-ci.outputs.tests-include || needs.plan.outputs.rows) }}
> ```
>
> * Pass the planner's output unchanged, and make it the job's whole matrix,
>   with no other keys beside `include:`.
> * Use `<job>-matrix` instead if the job reads a whole matrix object at
>   `strategy.matrix`.
> * The keys you choose also define what a variation is, so changing them later
>   starts every group's history over.

### Check that it works

Once a pull request skips some variations, the Dynamic CI step's log names each
group and its decision:

```text theme={"system"}
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 pull request that edits the workflow file itself can run every variation, so
check on one that changes something else.
