GitHub Actions matrix with a reusable workflow limitation in CI

By Kaveh Alemi·Latchkey

You can fan out a reusable-workflow call with strategy.matrix, but the matrixed job stays a pure call: it may set with: and secrets: from matrix values, and it cannot contain steps. Passing matrix values into undeclared inputs also fails.

What this error means

A matrixed calling job fails to parse because it also has steps, or because it passes a matrix value into an input the reusable workflow does not declare.

Invalid workflow file: .github/workflows/ci.yml#L15
The job "deploy" calls a reusable workflow and uses a matrix, so it cannot
define "steps"; pass matrix values through "with" only.

Common causes

The matrixed calling job also has steps

As with any calling job, adding steps to a matrixed uses: job is invalid. The matrix only varies the inputs passed to each call.

A matrix value maps to an undeclared input

Passing with: env: ${{ matrix.env }} fails if the reusable workflow does not declare an env input.

How to fix it

Feed matrix values through with: only

1. Keep the matrixed job limited to uses, with, secrets, needs, if.
2. Map each matrix key to a declared input in with:.
3. Move any per-combination steps inside the reusable workflow.

jobs:
  deploy:
    strategy:
      matrix:
        environment: [staging, production]
    uses: ./.github/workflows/deploy.yml
    with:
      environment: ${{ matrix.environment }}

Declare every input the matrix supplies

Add each matrixed value as a declared input on the reusable workflow so the mapping is valid.

inputs:
  environment:
    required: true
    type: string

How to prevent it

• Keep matrixed calling jobs limited to call keys only.
• Declare an input for every matrix value you pass in with:.
• Put per-combination steps inside the reusable workflow.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions