{{ summaryTitle }}
{{ summaryPrimary }}
{{ summarySecondary }}
{{ badge.label }}
Use the name your team expects to see in pull request checks.
Choose the toolchain that owns the matrix version axis.
Examples: 20, 22, 24 for Node.js or 3.11, 3.12, 3.13 for Python.
Comma-separated or one-per-line runner labels.
Keep install work deterministic, for example npm ci or python -m pip install -r requirements.txt.
Use the command that should decide whether each matrix job passes.
Setup-action cache is the default for package-manager workflows with lockfiles.
Enter a .yml or .yaml file name.
Examples: test, build, ci_matrix.
Comma-separated or one-per-line branch names.
Human-readable runtime label for job names.
Examples: actions/setup-node@v6, actions/setup-python@v6, actions/setup-go@v6.
Examples: node-version, python-version, go-version, java-version.
Use for inputs such as distribution=temurin or check-latest=true.
Examples: npm, pnpm, pip, poetry, gradle, maven, true.
Examples: package-lock.json or frontend/package-lock.json.
Accepts one path or a block of paths.
Example: frontend or packages/api.
Leave blank unless every matrix job should vary by another dimension.
Example: npm, pnpm, yarn.
Example: os=ubuntu-latest,node-version=25,experimental=true.
Example: os=windows-latest,node-version=20.
Use a positive number to cap concurrent matrix jobs.
jobs
Set a realistic ceiling for one matrix job.
min
Leave off when you want the full compatibility picture from every axis.
{{ fail_fast ? 'On' : 'Off' }}
Often paired with the default branch for CI coverage after merge.
{{ trigger_push ? 'On' : 'Off' }}
Turn on for branch protection and compatibility checks before merge.
{{ trigger_pull_request ? 'On' : 'Off' }}
Useful before adding a workflow to required checks.
{{ trigger_workflow_dispatch ? 'On' : 'Off' }}
Recommended for ordinary test workflows.
{{ permissions_contents_read ? 'On' : 'Off' }} 
{{ workflowYaml }}
Runner OS {{ versionAxisLabel }} Extra axis Source Experimental Copy
{{ row.os }} {{ row.version }} {{ row.extraAxis }} {{ row.source }} {{ row.experimental ? 'yes' : 'no' }}
Check Status Detail Copy
{{ row.check }} {{ row.status }} {{ row.detail }}
Tags: Automation, Devops, Devtools
Export to PDF Fullscreen
Customize
Advanced
:

GitHub Actions matrix workflows run one job definition across several planned environments. A single test job can cover multiple runtime versions, runner operating systems, package managers, database versions, or other compatibility choices without copying the same job over and over.

The value of a matrix is confidence with discipline. Testing Node.js 20, 22, and 24 on Ubuntu and macOS can reveal version or platform drift before a merge, but every new axis multiplies CI time, queue pressure, and review noise. The best matrix names the combinations that actually affect release confidence instead of expanding every possible environment by habit.

GitHub Actions matrix axes combining runner operating systems and runtime versions into job rows.

A useful workflow matrix also needs a clear failure policy. Some teams want every combination to finish so they can see the full compatibility picture. Others want fail-fast behavior to stop queued work after a required job fails. GitHub Actions supports both choices, so the policy should match the reason the matrix exists.

Generated workflow YAML is still a starting point. The repository must contain the lockfiles, test commands, language setup, and runner labels named by the workflow, and GitHub is the final authority on whether the committed workflow can run in that repository.

Technical Details:

A matrix strategy creates job runs from axis values. With runner operating systems and runtime versions, GitHub evaluates every operating-system and version pairing, then assigns each job its own matrix context. That context is commonly used in runs-on, setup-action inputs, job names, and cache keys.

The planned job count grows by multiplication before exceptions are applied. GitHub documents a 256-job limit per matrix workflow run, so a third axis such as package manager, architecture, or database version should be added only when the extra coverage changes a release decision.

jobs = ( O × V × A ) - E + I

In this planning equation, O is the number of runner OS labels, V is the number of runtime versions, A is the optional extra-axis count or 1 when no extra axis is used, E is the number of base combinations removed by exclude rules, and I is the number of include rows added to the ledger.

Rule Core:

Workflow part Generated rule What to verify
strategy.matrix Runner OS labels, runtime versions, and an optional extra axis become YAML lists. The summary count and Matrix Ledger should match the combinations you intend to test.
include Each key-value row is emitted under strategy.matrix.include and shown as an added ledger row. Use complete include rows when you want a standalone exception job.
exclude Each row removes base combinations whose keys all match the exclusion values. Check that a partial exclude row does not remove more operating systems or versions than intended.
fail-fast The generated workflow writes true or false under strategy.fail-fast. false keeps the full compatibility run visible after one required job fails.
max-parallel 0 omits the setting. A positive value from 1 to 256 caps concurrent matrix jobs. Use a cap when runner supply, rate limits, or service dependencies cannot handle the full matrix at once.
timeout-minutes The job timeout is clamped to a whole number from 1 to 360 minutes. Set a ceiling that catches stuck jobs without killing normal slow combinations.

Validation and Output Surfaces:

Output cue Meaning Boundary
Workflow YAML Copy-ready workflow text with triggers, permissions, setup, install, test, cache, and matrix strategy. YAML is not submitted to GitHub or checked against repository files.
Matrix Ledger One planning row per computed combination, with runner OS, runtime version, extra axis, source, and experimental flag. A ledger row is planned CI coverage, not proof that a job has run.
Workflow Checks OK, Review, or Blocked rows for path, matrix count, setup action, cache, triggers, fail-fast, timeout, warnings, and errors. OK means the generated configuration passed local rules, not that GitHub accepted the workflow.
Check workflow inputs Blocking errors appear when required versions, OS labels, commands, triggers, or extra-axis pairings are missing. Workflow YAML stays empty until blocking errors are fixed.
Review before committing Warnings flag parse issues, missing setup or cache details, generic dependency paths, and matrices over 256 jobs. Warnings do not block output, but they should be resolved before adding a required CI check.

Everyday Use & Decision Guide:

Pick the runtime preset first. Node.js, Python, Go, and Java presets load the setup action, version input name, install command, test command, dependency path, and cache defaults for common projects. Use Custom setup action when the runtime is already present on the runner or when a private action owns setup.

Keep the first pass small enough to review. Two runner OS labels and three runtime versions create six jobs before any extra axis is added. Add Extra matrix axis name only when every base job should vary by that extra value, such as package-manager with npm and pnpm.

  • Use Workflow name, Workflow file, and Job id values that match branch protection and repository conventions.
  • Leave Fail-fast off when the goal is a full compatibility picture across all versions and runner labels.
  • Use Setup action cache when the selected setup action supports the package manager and lockfile path you provide.
  • Use Manual actions/cache step only when you know the cache path that should be restored on the runner.
  • Read Workflow Checks before copying YAML. Review is often the signal that a workflow would run but still surprise the team.

The output is a good fit for a test or build workflow that checks runtime compatibility. It is a poor fit for release publishing, deployment credentials, or workflows that need environment approvals, secrets, services, artifacts, concurrency groups, or reusable workflow calls, because those pieces are not modeled here.

After the checks look right, copy Workflow YAML into the named workflow path and run it with workflow_dispatch before making it a required check.

Step-by-Step Guide:

Build the workflow from the runtime outward, then use the review tables to catch combinations that grew too large or lost a required trigger.

  1. Choose Runtime preset. Confirm that Runtime label, Setup action, Version input name, Install command, and Test command change to the expected language defaults.
  2. Enter Runtime versions and Runner OS labels as comma-separated or one-per-line lists. The summary should update to the computed number of matrix jobs.
  3. Set Workflow name, then open Advanced for Workflow file, Job id, Push branches, and Working directory when the defaults do not match the repository.
  4. Choose Dependency cache. If a warning says the setup-action cache has no package/input or the manual cache has no path, fill Cache package/input, Dependency path, or Manual cache path.
  5. Add Extra matrix axis name, Matrix include rows, and Matrix exclude rows only when the base matrix needs exceptions. If the error list says the extra axis is incomplete, add the missing axis name or clear the values.
  6. Set Fail-fast, Max parallel, Timeout, and trigger switches. If all triggers are off, the tool shows Enable at least one trigger. and does not render workflow YAML.
  7. Review Workflow YAML, Matrix Ledger, Workflow Checks, and JSON. Copy or download the YAML only after Blocking errors reports OK and any Review rows are intentional.

Interpreting Results:

GitHub Actions matrix ready means the input rules produced workflow YAML. The primary number is the planned job count, so read it with the Matrix combinations check before committing the workflow.

OK rows in Workflow Checks should still be checked against repository reality. A setup action can be syntactically present while the requested runtime version, package manager, or lockfile path is wrong for the project.

  • Blocked means a required input is missing or no trigger is enabled, and the YAML output is intentionally empty.
  • Review on Matrix combinations usually means the count is over GitHub's 256-job matrix limit.
  • Review on Fail-fast policy means failed required jobs can cancel queued or running matrix jobs.
  • Review on Dependency cache means no cache is emitted, a manual cache path is missing, or generic lockfile globs are being used.

Worked Examples:

Default Node.js CI. The default Node.js preset uses versions 20, 22, and 24 with ubuntu-latest and macos-latest. The summary reports 6 jobs, Workflow path shows .github/workflows/ci.yml, and Workflow YAML uses actions/setup-node@v6 with node-version from the matrix.

Python with one excluded runner. A Python matrix with versions 3.11, 3.12, and 3.13 across ubuntu-latest and windows-latest starts at six jobs. Adding os=windows-latest,python-version=3.13 to Matrix exclude rows removes that base combination, so Matrix Ledger should show five rows and the generated YAML should include an exclude entry.

Package-manager axis with an experimental include row. Node.js versions 20 and 22 across two runner labels become four jobs. Adding package-manager with values npm and pnpm expands the plan to eight jobs. An include row such as os=ubuntu-latest,node-version=24,package-manager=pnpm,experimental=true adds one ledger row marked experimental and emits continue-on-error: ${{ matrix.experimental == true }}.

Missing trigger troubleshooting. If Push trigger, Pull request trigger, and Manual trigger are all off, the error list says Enable at least one trigger.. Turn on Manual trigger for a safe first run, then confirm Blocking errors returns to OK before using the YAML.

FAQ:

Does the generator test the workflow in GitHub?

No. It builds workflow YAML, a matrix ledger, workflow checks, and JSON from the entered values. Commit the YAML to the repository and run it with workflow_dispatch to confirm GitHub accepts it.

Why is no YAML shown?

At least one blocking error is present. Common causes are empty Runtime versions, empty Runner OS labels, missing install or test commands, no enabled trigger, or extra-axis values without an axis name.

Why did the job count exceed the GitHub limit?

The job count multiplies runner labels by runtime versions and any extra-axis values, then applies excludes and include rows. Reduce an axis, add excludes, or split the workflow when Matrix combinations reports more than 256 jobs.

Should include rows be complete combinations?

Yes for predictable review. The ledger treats each include row as an added row, so include the runner label, version input, extra-axis value when present, and any experimental=true flag you expect to see.

Does the tool send repository secrets or workflow content to GitHub?

The generated workflow is built in the browser and the tool does not call the GitHub API. Copy and download actions use the current page output rather than pushing content to a repository.

Glossary:

Matrix axis
A named list of values, such as runner OS labels or runtime versions, that GitHub combines into jobs.
Runner OS label
The runs-on value that tells GitHub which runner environment should execute a job.
Setup action
An action such as actions/setup-node or actions/setup-python that prepares a runtime before install and test commands run.
Include row
An extra matrix entry emitted under strategy.matrix.include.
Exclude row
A key-value rule that removes matching base matrix combinations.
Fail-fast
A matrix policy that can cancel queued or in-progress jobs after a required matrix job fails.
Workflow trigger
An event such as push, pull_request, or workflow_dispatch that starts a workflow run.

References: