How do you build a GitHub Actions matrix at runtime from a previous job's output?

## Why a dynamic matrix A static matrix is fine while the list of things to build is stable. It stops being fine when the list lives in the repository — one job per service directory in a monorepo, one job per changed package, one job per supported version read from a config file. Duplicating that list in YAML means it silently drifts. Generating it means the workflow follows the repository. ## The mechanic Three pieces have to fit together. **1. Produce JSON in a step and expose it as a job output.** jobs: setup: runs-on: ubuntu-latest outputs: services: ${{ steps.list.outputs.services }} steps: - uses: actions/checkout@v4 - id: list run: | json=$(ls -d services/*/ | xargs -n1 basename | jq -R -s -c 'split("\n")[:-1]') echo "services=$json" >> "$GITHUB_OUTPUT" Step outputs are written as `name=value` lines to the file named by `GITHUB_OUTPUT`, then surfaced at job level through the job's `outputs:` map. **2. Parse it in the consumer.** Job outputs are strings, so the matrix cannot use the value directly: build: needs: setup strategy: matrix: service: ${{ fromJSON(needs.setup.outputs.services) }} runs-on: ubuntu-latest steps: - run: ./build.sh "${{ matrix.service }}" `fromJSON` parses a JSON string into a value the expression engine understands — here an array bound to the `service` matrix key. **3. Choose the shape.** Two forms are common. Assigning to a single key, as above, needs a JSON **array** of scalars. Assigning to the whole matrix — `matrix: ${{ fromJSON(needs.setup.outputs.config) }}` — needs a JSON **object** with the same structure the YAML would have had, for example `{"include":[{"service":"api","os":"ubuntu-latest"}]}`. The object form is what you use when the legs are heterogeneous, since it can carry an `include` list directly. ## Practical rules - **Emit compact, single-line JSON.** `jq -c` exists for this. A multi-line value needs the heredoc delimiter form of `GITHUB_OUTPUT` and is easy to get wrong. - **Handle the empty list.** An empty array produces zero matrix jobs and the job is skipped, which then makes anything depending on it skip too. Either emit a placeholder, or gate the consumer with an explicit condition, or make downstream jobs tolerate the skip with an `if:` that uses `always()` plus a result check. - **Print the JSON before publishing it.** A malformed string fails at expression evaluation with a message that points at the matrix rather than at the generator, so `echo` it in the setup job to make debugging one glance instead of five runs. - **Keep the generator cheap.** The setup job's own startup — runner allocation, checkout — is pure overhead added in front of every downstream job, so it should be a small ubuntu job with a shallow checkout, not a full build. - **Respect the ceiling.** One matrix in a run is capped at 256 jobs. A generator over a large monorepo can hit that; cap or bucket the list yourself rather than discovering the limit on a busy day. - **Treat generated values as data.** If any part of the JSON derives from a branch name, a pull-request title, or another attacker-influenceable field, do not splice it into a `run:` command via `${{ }}`; pass it through `env:` and quote it. ## Where the value usually comes from Common generators are a directory listing (one leg per service), a parse of a config or manifest file with `jq`, a changed-paths computation so only affected packages build, and a `gh api` call to list something like open release branches. The changed-paths variant is the highest-value one in a monorepo: it turns a fixed 30-job matrix into a two-job matrix on the average pull request. ## Summary answer "Setup job writes a JSON array to `GITHUB_OUTPUT` and exposes it as a job output; the build job takes `needs:` on it and sets `matrix:` to `fromJSON(...)` of that output. `fromJSON` is required because outputs are strings, and the empty-list case has to be handled deliberately."