Matrix & Advanced Patterns

Matrix strategies, dynamic matrices, concurrency control, conditional workflows, and workflow orchestration patterns.

🧒 Simple Explanation (ELI5)

Imagine you run a restaurant kitchen.

• Matrix strategy is like having multiple cooks prepare the same dish with different ingredients simultaneously. Instead of testing your app on Node 18, then Node 20, then Node 22 one after another, the matrix fires up three kitchens (runners) at the same time — one for each version. Add three operating systems and you have 9 cooks working in parallel (3 OS × 3 Node versions).
• fail-fast is the head chef shouting "Stop everything!" the moment one cook burns their dish. If disabled, every cook finishes regardless — useful when you want the full picture of what's broken.
• Concurrency is the kitchen capacity rule. You can say "only one dessert order at a time" so two soufflés don't collide in the oven. In CI/CD, this means "only one deploy to production at a time" — if a new one starts, cancel the old one that's still baking.
• Dynamic matrix is like the head chef reading tonight's reservation list and dynamically deciding which dishes to prep — instead of a fixed menu, the matrix is generated on the fly based on what's actually needed.

Put it together: the matrix multiplies your testing, concurrency prevents collisions, and dynamic matrices make everything smart and adaptive.

🔢 Matrix Strategy

A matrix strategy lets you run the same job across multiple combinations of variables — OS versions, language versions, configurations — all in parallel.

Basic Matrix

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        node: [18, 20, 22]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - run: npm ci
      - run: npm test

This creates 9 jobs (3 OS × 3 Node versions). Each combination runs as an independent job. Access values via ${{ matrix.os }} and ${{ matrix.node }}.

fail-fast & max-parallel

• fail-fast: true (default) — if any matrix job fails, GitHub cancels all remaining jobs immediately. Fast feedback, but you lose visibility into other failures.
• fail-fast: false — all jobs run to completion regardless of failures. Essential when you need the full compatibility picture.
• max-parallel — limit how many matrix jobs run concurrently. Useful when jobs consume expensive resources (e.g., limited self-hosted runners).

strategy:
  fail-fast: false
  max-parallel: 4
  matrix:
    os: [ubuntu-latest, windows-latest, macos-latest]
    node: [18, 20, 22]

Include & Exclude

Fine-tune the matrix by adding or removing specific combinations:

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
    node: [18, 20]
    include:
      # Add an extra combination not in the base matrix
      - os: ubuntu-latest
        node: 22
        experimental: true
    exclude:
      # Remove a specific combination
      - os: windows-latest
        node: 18

• include adds extra combinations (or extra variables to existing ones). The experimental: true variable is accessible as ${{ matrix.experimental }}.
• exclude removes specific combinations from the Cartesian product. Here, Windows + Node 18 is skipped entirely.
• Result: ubuntu-18, ubuntu-20, ubuntu-22 (included), windows-20 — total 4 jobs instead of 4.

Using Extra Matrix Variables

strategy:
  matrix:
    include:
      - os: ubuntu-latest
        node: 22
        experimental: true
      - os: ubuntu-latest
        node: 20
        experimental: false
steps:
  - run: npm test
    continue-on-error: ${{ matrix.experimental }}

This lets experimental builds fail without breaking the overall workflow — perfect for testing pre-release versions.

⚡ Dynamic Matrix

Instead of hardcoding the matrix in YAML, generate it dynamically from a previous job's output. This is essential for monorepos, version detection, and conditional testing.

Basic Pattern — JSON File

jobs:
  setup:
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.set-matrix.outputs.matrix }}
    steps:
      - uses: actions/checkout@v4
      - id: set-matrix
        run: echo "matrix=$(jq -c . matrix.json)" >> $GITHUB_OUTPUT

  build:
    needs: setup
    runs-on: ubuntu-latest
    strategy:
      matrix: ${{ fromJson(needs.setup.outputs.matrix) }}
    steps:
      - uses: actions/checkout@v4
      - run: echo "Building ${{ matrix.service }} v${{ matrix.version }}"

Example matrix.json

{
  "service": ["api", "web", "worker"],
  "version": ["1.0", "2.0"]
}

Monorepo — Detect Changed Services

jobs:
  detect:
    runs-on: ubuntu-latest
    outputs:
      services: ${{ steps.changed.outputs.services }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - id: changed
        run: |
          CHANGED=$(git diff --name-only HEAD~1 HEAD | grep -oP '^services/\K[^/]+' | sort -u | jq -Rc . | jq -sc .)
          echo "services=$CHANGED" >> $GITHUB_OUTPUT

  build:
    needs: detect
    if: needs.detect.outputs.services != '[]'
    runs-on: ubuntu-latest
    strategy:
      matrix:
        service: ${{ fromJson(needs.detect.outputs.services) }}
    steps:
      - uses: actions/checkout@v4
      - run: cd services/${{ matrix.service }} && make build

Use cases: monorepo (only build changed services), dynamic version lists (fetch supported versions from an API), environment-specific deploys (generate targets from a config file).

🚦 Concurrency Control

Concurrency groups prevent multiple instances of the same workflow from running simultaneously — critical for deployments, releases, and resource-intensive jobs.

Basic Concurrency

# Workflow-level concurrency
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

on:
  push:
    branches: [main]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test

• group — a name that identifies concurrent runs. Runs with the same group name are serialized or cancelled.
• cancel-in-progress: true — if a new run starts in the same group, cancel the currently running one. Perfect for PR checks where only the latest push matters.
• cancel-in-progress: false — new runs queue and wait for the current one to finish. Use for deployments where you never want to interrupt a running deploy.

Workflow-Level vs Job-Level

# Job-level concurrency — only the deploy job is serialized
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - run: npm test

  deploy:
    needs: test
    runs-on: ubuntu-latest
    concurrency:
      group: deploy-production
      cancel-in-progress: false
    steps:
      - run: ./deploy.sh production

Workflow-level concurrency applies to the entire workflow run. Job-level concurrency lets you serialize only specific jobs — tests can run concurrently, but deploys are serialized.

Concurrency Group Naming Patterns

🧩 Advanced Workflow Patterns

Conditional Workflows

Skip jobs based on event context, file changes, or custom conditions:

jobs:
  deploy:
    # Skip deploys for draft PRs
    if: github.event.pull_request.draft == false
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy.sh

  docs:
    # Only run when docs change
    if: contains(github.event.head_commit.message, '[docs]')
    runs-on: ubuntu-latest
    steps:
      - run: ./build-docs.sh

Path-Based Job Execution

Use dorny/paths-filter to conditionally run jobs based on which files changed:

jobs:
  changes:
    runs-on: ubuntu-latest
    outputs:
      backend: ${{ steps.filter.outputs.backend }}
      frontend: ${{ steps.filter.outputs.frontend }}
    steps:
      - uses: actions/checkout@v4
      - uses: dorny/paths-filter@v3
        id: filter
        with:
          filters: |
            backend:
              - 'server/**'
            frontend:
              - 'client/**'

  backend-tests:
    needs: changes
    if: needs.changes.outputs.backend == 'true'
    runs-on: ubuntu-latest
    steps:
      - run: cd server && npm test

  frontend-tests:
    needs: changes
    if: needs.changes.outputs.frontend == 'true'
    runs-on: ubuntu-latest
    steps:
      - run: cd client && npm test

Workflow Chaining — workflow_run

Trigger a workflow after another workflow completes:

# deploy.yml — runs after CI completes on main
on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]
    branches: [main]

jobs:
  deploy:
    if: github.event.workflow_run.conclusion == 'success'
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy.sh

Repository Dispatch — Cross-Repo Triggers

# In Repo B — listens for dispatch events
on:
  repository_dispatch:
    types: [deploy-frontend]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying version ${{ github.event.client_payload.version }}"

# In Repo A — sends the dispatch event
- uses: peter-evans/repository-dispatch@v3
  with:
    token: ${{ secrets.REPO_B_PAT }}
    repository: myorg/repo-b
    event-type: deploy-frontend
    client-payload: '{"version": "1.2.3"}'

Timeout & Retry Patterns

jobs:
  deploy:
    runs-on: ubuntu-latest
    timeout-minutes: 30          # Kill job if it exceeds 30 minutes
    steps:
      - name: Deploy with retry
        uses: nick-fields/retry@v3
        with:
          timeout_minutes: 10
          max_attempts: 3
          retry_on: error
          command: ./deploy.sh

      - name: Flaky integration test
        run: npm run test:e2e
        continue-on-error: true  # Don't fail the job if this step fails

• timeout-minutes — hard limit on job duration (default: 360 minutes). Set it to prevent stuck jobs from burning runner hours.
• continue-on-error: true — the step can fail without failing the job. Combine with subsequent status checks for retry logic.
• Retry action — nick-fields/retry retries a command on failure with configurable attempts and backoff.

📋 Pattern Catalog

📊 Visual Diagrams

Matrix Expansion

strategy:
  matrix:
    os: [ubuntu, windows, macos]
    node: [18, 20, 22]

         ┌─────────────────────────────────────────────────────┐
         │               Matrix Expansion (9 Jobs)             │
         └─────────────────────────────────────────────────────┘

         ubuntu + Node 18 ──┐
         ubuntu + Node 20 ──┤
         ubuntu + Node 22 ──┤
         windows + Node 18 ─┤──▶  All run in parallel
         windows + Node 20 ─┤     (limited by max-parallel)
         windows + Node 22 ─┤
         macos + Node 18 ───┤
         macos + Node 20 ───┤
         macos + Node 22 ───┘

         With exclude: [{os: windows, node: 18}]
         → 8 jobs (windows + Node 18 removed)

         With include: [{os: ubuntu, node: 23, experimental: true}]
         → 10 jobs (extra combination added)

Concurrency Group Cancellation Flow

concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

Timeline:
─────────────────────────────────────────────────────▶ time

Push A (branch: feat-1)
  ├── Run #1 starts ─────────────────────▶ running...
  │
Push B (branch: feat-1)                     ← same group
  │   Run #1 ──❌ CANCELLED
  ├── Run #2 starts ─────────────────────▶ running...
  │
Push C (branch: feat-2)                     ← different group
  ├── Run #3 starts ─────────────────────▶ ✅ completes
  │   (Run #2 continues — different group)
  │
Push D (branch: feat-1)                     ← same group as #2
      Run #2 ──❌ CANCELLED
  ├── Run #4 starts ─────────────────────▶ ✅ completes

🛠️ Hands-on Lab

Lab 1: Create a Multi-OS × Multi-Node Matrix

1. Create .github/workflows/matrix-test.yml
2. Define a matrix with os: [ubuntu-latest, windows-latest] and node: [18, 20, 22]
3. Set fail-fast: false to see all results
4. Push and verify 6 jobs appear in the Actions tab

name: Matrix Test
on: push

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest]
        node: [18, 20, 22]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - run: node --version
      - run: npm ci
      - run: npm test

Lab 2: Add Include / Exclude

1. Exclude windows-latest + Node 18 (known incompatibility)
2. Include ubuntu-latest + Node 23 with experimental: true
3. Use continue-on-error: ${{ matrix.experimental || false }} on the test step
4. Verify: 6 jobs (6 base – 1 excluded + 1 included), experimental allowed to fail

Lab 3: Dynamic Matrix from JSON

1. Create a matrix.json file: {"node": [18, 20, 22], "os": ["ubuntu-latest"]}
2. Create a setup job that reads the file and outputs the matrix
3. Create a test job that consumes fromJson(needs.setup.outputs.matrix)
4. Modify the JSON and push — observe the matrix changing without editing the workflow

Lab 4: Concurrency for Deployments

1. Add a workflow-level concurrency group: ${{ github.workflow }}-${{ github.ref }}
2. Set cancel-in-progress: true
3. Push two commits in rapid succession to the same branch
4. Observe the first run being cancelled and only the second completing
5. Change to cancel-in-progress: false and repeat — observe queuing behavior

🐛 Debugging Common Issues

"Matrix generates 0 jobs"

• Cause: An empty array in the matrix definition, or a dynamic matrix that evaluates to []
• Fix: Add an if guard: if: fromJson(needs.setup.outputs.matrix).service[0] != null. Or ensure the array always has at least one element
• Check: Print the matrix output in the setup job: echo "${{ steps.set-matrix.outputs.matrix }}"

"Concurrency cancels the wrong run"

• Cause: The concurrency group name is too broad — e.g., using ${{ github.workflow }} without ${{ github.ref }}
• Fix: Include branch/PR context: group: ${{ github.workflow }}-${{ github.ref }}
• Debugging: Check the "Concurrency group" label in the Actions run summary to see which group the run belongs to

"Dynamic matrix: invalid JSON"

• Cause: fromJson() received a malformed string — newlines, trailing commas, or shell escaping issues
• Fix: Always use jq -c (compact output) and wrap in quotes when setting output. Verify with: echo '$JSON' | jq .
• Common mistake: Multi-line JSON in $GITHUB_OUTPUT — output values must be single-line

"Include adds new combinations but variables are empty"

• Cause: include entries that don't match any existing matrix combination create new combinations — but extra variables only apply to matched combos
• Fix: Ensure include entries specify all matrix dimensions if they need to match, or explicitly add all needed variables for new combinations

🎯 Interview Questions

Basic (5)

Intermediate (5)

Senior (5)

🏭 Real-World Scenario

An open-source Node.js library with 2,000+ stars needed comprehensive cross-platform testing before every release. Here's how they implemented it:

Challenge:

• Support 5 OS targets (Ubuntu, Windows, macOS, Alpine, Amazon Linux) × 4 Node versions (18, 20, 22, 23)
• Node 23 was pre-release — failures should not block the pipeline
• PRs were getting rapid-fire commits, wasting runner minutes on stale checks
• Release builds needed to publish to npm only once, not per-matrix-job

Solution:

• Matrix with include/exclude: Base: 5 OS × 3 stable Node = 15 jobs. Include: {os: ubuntu-latest, node: 23, experimental: true}. Exclude: {os: amazonlinux, node: 18} (EOL). Total: 15 jobs
• fail-fast: false — maintainers wanted to see the full compatibility matrix in every run
• continue-on-error: ${{ matrix.experimental || false }} — Node 23 failures logged but didn't block
• Concurrency: group: ci-${{ github.event.pull_request.number || github.ref }} with cancel-in-progress: true — only the latest push is tested
• Fan-in publish job: needs: [test] runs after all matrix jobs complete. Only triggers on tag push (if: startsWith(github.ref, 'refs/tags/v')) and publishes a single npm package
• Dynamic nightly matrix: A scheduled workflow fetches the list of active Node versions from the Node.js release API and generates the matrix dynamically. No YAML changes needed when Node 24 drops

Results:

• PR check time reduced from 45 minutes to 12 minutes (concurrency cancellation + caching)
• Caught 3 platform-specific bugs in the first month that would have shipped to users
• Node 23 compatibility ready on day one of stable release — zero scramble
• Runner minutes dropped 60% from concurrency alone

📝 Summary

• Matrix strategy: Run the same job across every combination of OS, language, and config. Use fail-fast: false for full visibility, max-parallel to control resource usage
• Include / Exclude: Fine-tune the matrix — add experimental builds with include, remove incompatible combos with exclude
• Dynamic matrix: Generate the matrix from JSON files, APIs, or git diffs. Essential for monorepos and config-driven pipelines. Always use jq -c and fromJson()
• Concurrency: Prevent duplicate runs with named groups. Use cancel-in-progress: true for PR checks, false for deployments. Always include github.ref in the group name
• Advanced patterns: Conditional jobs, path-based filtering, workflow chaining (workflow_run), cross-repo dispatch, timeout and retry strategies
• Orchestration: Fan-out/fan-in, canary, blue-green, feature flags — combine matrix, concurrency, and environments for production-grade pipelines