GitHub Actions Matrix Generator

GitHub Actions matrix generator for parallel environment testing

GitHub Actions matrix generator creates a ready-to-save .github/workflows/ci.yml file that runs the same test suite across multiple operating systems and PHP or Node versions. Choose dimensions, exceptions, and extra combinations to get correctly indented YAML with dependency caching, restricted permissions, and a guard against an oversized job matrix.

Why use a matrix strategy

One green build in one environment does not prove that the entire support range works. A package may pass on PHP 8.3 but fail on 8.2, a frontend may behave differently on Node 20 and 22, and a shell command may run on Ubuntu but break on Windows. The strategy.matrix block describes these variants once, then GitHub expands them into separate jobs that can run in parallel.

Dimension products and the job limit

A matrix is a Cartesian product. Two operating systems, two PHP versions, and three Node versions produce 2 x 2 x 3 = 12 base jobs. Every job consumes runner minutes and installs dependencies, so a larger matrix is not automatically better CI. The generator calculates a conservative upper bound as the base product plus include entries and rejects configurations above the GitHub Actions limit of 256 jobs.

Start with Ubuntu and the runtime versions your project officially supports. Add Windows or extra releases only when that compatibility is part of the contract. A full matrix is useful for pull requests targeting the default branch, while expensive integration suites can later move to a separate scheduled or manually triggered workflow.

How to configure matrix, include, and exclude

1. Enter a workflow name and the branches that should trigger push and pull_request events.
2. Provide at least one runner operating system and one PHP or Node version. Separate values with commas.
3. If a specific combination is unsupported, add an exclude line such as os=windows-latest, php=8.2, node=20.
4. If you need a variant outside the base lists, add a similar set under include. Only active dimensions are accepted.
5. Enable caches, tests, and lint tasks that match the repository, then save the output as .github/workflows/ci.yml.
6. Before committing, check it with the YAML validator and adjust php artisan test, npm test, and npm run lint.

Safe YAML scalar quoting

Branch names, runner labels, and version values are emitted as quoted scalars. This matters for text containing a colon, a # character, boolean-like words, or dotted version numbers. Without quotes, a YAML parser could interpret part of the value as a comment, number, or another key. The generator also rejects control characters and line breaks in single-line fields, preventing form data from injecting another workflow section.

Indentation uses two spaces, and include and exclude entries are lists of mappings. Each rule therefore preserves the relationship between its dimensions. Duplicate dimension values and identical rules are removed before output is built.

Minimum permissions and cost control

The workflow explicitly sets permissions: contents: read. Tests can read the repository checked out by the job but receive no permission to write code, issues, or packages. A fixed timeout-minutes: 30 also prevents a hung command from consuming runner time indefinitely. If you later add release publishing, deployment, or pull request comments, grant extra permissions only to the job that needs them.

Official action versions and dependency caching

The generated file uses current major releases of official actions: actions/checkout@v7, actions/setup-node@v7, and actions/cache@v6. The community shivammathur/setup-php action remains on @v2 because that is its current major line. Pinning to a major receives compatible fixes; a higher-security environment can manually replace a major tag with a full commit SHA.

npm caching is handled by setup-node and keyed from package-lock.json. Composer download caching uses actions/cache, the runner operating system, the PHP version, and the hash of composer.lock. A lockfile change creates a fresh key, while the restore prefix can reuse the nearest previous cache. You can compare the same pipeline concepts with the GitLab CI generator.

What to customize after generation

The tool cannot infer the commands defined by a particular repository. php artisan test fits Laravel, while a library may require vendor/bin/phpunit or vendor/bin/pest. Likewise, npm test and npm run lint must exist in the scripts section of package.json. If the project builds a container, prepare its base with the Dockerfile generator; for a self-managed CI server, compare the output with the Jenkinsfile generator.

Also verify that every selected operating system can execute manually added commands. GitHub uses different default shells on Windows and Linux. Composer, npm, and PHP commands are portable, but a custom Bash script may need an explicit shell: bash setting or an Ubuntu-only matrix rule.

Frequently asked questions