How to Turn a Test Plan into a GitHub Actions Matrix
CI prompts fail by inventing secrets, ubuntu images, Node versions, and a codecov token you never created. The workflow file looks complete. First run dies on a missing secret. Second run dies on a matrix combination the test plan never asked for. You then maintain YAML that does not match the plan.
The matching generator is the GitHub Actions Matrix from a Test Plan prompt. Browse related cards in the PromptDig library (Browse more prompts). When a filled run survives, share the version you actually use (Share a prompt).
Restate the plan, then pin what you can prove
Five bullets from Inputs only: which suites, which OS, which language versions, which browsers or databases, which event triggers. If the plan says unit tests on 20.x and 22.x and e2e only on Chromium, that is the matrix. Do not add Firefox because "everyone does."
Version-lock named tools. Actions get a pin you were given (a tag or a SHA). If the plan does not name an action version, write unknown and list it under Gaps. Do not silently float on v4 when v4 moved.
Runners: only the labels in the plan. Do not invent a self-hosted fleet or a macOS image to look thorough. If the plan is Linux-only, the workflow is Linux-only.
Matrix from the plan, secrets you already have
include and exclude exist so you do not run a combination the plan forbade. fail-fast is a choice you type. If the plan wants e2e skipped on pull requests from forks, say so in an if: and do not invent a secret to paper over it.
Secrets: only names that already exist in the repo or that the plan lists as required-and-missing. Do not mint CODECOV_TOKEN, NPM_TOKEN, or a Docker hub password to complete the file. If a secret is required and absent, the output should say NOT IN INPUTS and refuse to reference it.
Environment variables that encode versions belong next to the matrix, not scattered in run: blocks as magic numbers the plan did not contain.
Services (Postgres, Redis) only if the test plan starts them. Image tags from Inputs. If the tag is missing, unknown, not latest-as-a-guess.
Edge cases, a checklist, and UNVERIFIED items
Fork PRs, skipped paths, concurrency groups that cancel outdated runs, and artifact upload on failure: include them when the plan mentions them. If it does not, list them as gaps instead of a "best practice" dump that adds permissions: write-all.
Validation checklist: workflow_dispatch dry run, one matrix cell locally if you have a runner, secret names grepped against repo settings, pin audit for unpinned actions. Do not claim the workflow is green.
Gaps and UNVERIFIED: real coverage thresholds, named owners, tool versions, required reviewers, OIDC role ARNs, and any third-party action the plan never named. Character caps in job names are hard if you set them. Print them.
Stay on the test plan. A lint job the plan did not ask for is scope creep. A deploy job definitely is.
Fill the card, then run
Paste the test plan and the versions you already pin in the repo. Empty secret names stay empty.
Goal: [Which suites must run]
Test plan / paste: [Plan]
Stack versions I can prove: [Node, Python, OS, browsers]
Constraints: [Forks, paths, timeouts, fail-fast]
Forbidden: [Secrets I do not have, extra OS, extra browsers]
Acceptance checks: [How I will know the YAML matches the plan]
A small pinned matrix that matches the plan is cheaper than a beautiful file that needs four new secrets. When a run leaves CODECOV_TOKEN under Gaps and excludes a cell the plan never wanted, share that filled card. That is the CI adapter other repos can copy.
Do not treat a passing syntax check as proof the matrix is right. Open the plan beside the YAML and tick each suite, OS, and version. If a cell has no owner in Inputs, it stays unowned. The generator should not assign a maintainer so the file looks staffed.