GitLab CI Matrix Generator

GitLab CI matrix generator for multiple versions

This generator creates a .gitlab-ci.yml file with build, test, optional deployment, and parallel: matrix. A single job template can test a project on several PHP, Node.js, or Python versions. Values are emitted as quoted YAML strings, preventing a version from being interpreted as a number, Boolean value, or a new configuration node.

The tool provides a secure starting point rather than a repository-specific pipeline. Its jobs call ./scripts/build.sh, ./scripts/test.sh, and ./scripts/deploy.sh, which you must adapt before committing the file. For a simpler pipeline without a matrix, compare the result with the GitLab CI generator. You can also inspect the finished document with the YAML validator.

How parallel: matrix works

When the matrix is enabled, the generator defines an environment-specific variable: PHP_VERSION, NODE_VERSION, or PY_VERSION. GitLab expands the definition into one job execution for each value. The container image uses an explicit variable boundary such as php:${PHP_VERSION}-cli, so the image suffix cannot become part of the variable name. With the matrix disabled, the first entered version is inserted directly and no undefined matrix variable remains.

test:
  stage: test
  image: 'php:${PHP_VERSION}-cli'
  parallel:
    matrix:
      - PHP_VERSION: ['8.2', '8.3']
  script:
    - ./scripts/test.sh

Stages and job consistency

The stages list controls execution order. The generator always creates build and test jobs, so both matching stages must be present and build must precede test. Enabling deployment also requires deploy after test. This check prevents a document that parses correctly but runs verification or deployment in the wrong order. Stage names use a restricted character set and bounded length.

Cache separated by branch and version

Sharing cached dependencies between incompatible runtimes can produce intermittent failures. The generated key therefore includes CI_COMMIT_REF_SLUG and the selected matrix version. The path follows the environment: vendor/ for PHP, node_modules/ for Node.js, and .cache/pip/ for Python. The pull-push policy lets a job download an existing cache and update it after completion.

Deployment on the default branch only

The deployment job uses rules to compare CI_COMMIT_BRANCH with CI_DEFAULT_BRANCH. This is safer than hard-coding main, because repositories may use another default branch. A branch rule does not replace protected environments, manual approvals, or secret protection. Keep credentials in protected and masked GitLab variables and never put them directly in YAML.

Generated file elements

How to prepare the configuration

1. Select PHP, Node.js, or Python and keep only the versions your project actually supports.
2. Define stages; retain build and test, and add deploy only when the repository has a reviewed deployment script.
3. Decide whether running the complete matrix on every branch is worth the runner time.
4. Generate the YAML, copy it to the repository root, and adapt all script commands.
5. Validate the YAML, use GitLab CI Lint, and run the pipeline on a test branch before merging.

Frequently asked questions