GitHub Actions matrix with reusable workflow "uses" limitations in CI

By Daniel Zoghalchali·Latchkey

A matrix job can call a reusable workflow, but a job that sets uses: cannot also have steps: or runs-on:. Matrix values reach the reusable workflow only through the with: inputs, and nested matrices in the called workflow are independent.

What this error means

The workflow fails validation because a uses: job also declares steps/runs-on, or matrix values do not reach the reusable workflow because they were not passed via with:.

This job defines both 'uses' and 'steps'. A job that calls a reusable
workflow cannot define steps.

Common causes

A uses job also declares steps or runs-on

A reusable-workflow call is the whole job. Mixing in steps: or runs-on: is invalid and rejected at parse time.

Matrix values were not passed as inputs

The reusable workflow cannot see the caller's matrix context. Each value must be forwarded explicitly through with:.

How to fix it

Forward matrix values through with

1. Make the matrix job a pure uses: call with no steps.
2. Pass each needed matrix value under with: as a declared input.
3. Read those inputs inside the reusable workflow.

jobs:
  build:
    strategy:
      matrix:
        node: [18, 20]
    uses: ./.github/workflows/reusable.yml
    with:
      node: ${{ matrix.node }}

Declare the inputs in the reusable workflow

Define matching workflow_call inputs so the forwarded matrix values are available inside.

on:
  workflow_call:
    inputs:
      node:
        required: true
        type: string

How to prevent it

• Keep reusable-workflow jobs as pure uses calls, no steps.
• Pass every matrix value the callee needs through with inputs.
• Declare matching workflow_call inputs in the reusable workflow.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions