How to Run a Reusable Workflow With a Matrix in GitHub Actions

You cannot put a matrix inside a reusable workflow caller block directly; the matrix has to live on the calling job.

Place strategy.matrix on the job that uses uses:, and pass each matrix value into the reusable workflow as an input via with.

Steps

• Define the reusable workflow with on: workflow_call and typed inputs.
• In the caller, add a job with a strategy matrix.
• Set uses: to the reusable workflow and pass matrix values via with.
• Each matrix combination invokes the reusable workflow once.

Workflow

name: Caller
on: [push]
jobs:
  deploy:
    strategy:
      matrix:
        env: [staging, prod]
    uses: ./.github/workflows/deploy.yml
    with:
      environment: ${{ matrix.env }}
    secrets: inherit
# deploy.yml
# on:
#   workflow_call:
#     inputs:
#       environment: { type: string, required: true }

Notes

• The matrix must sit on the calling job; a reusable workflow cannot define its own caller matrix.
• Latchkey managed runners run each reusable-workflow leg cheaper and self-heal on failure.

Related guides