act matrix strategy runs differently running Actions locally

By Kaveh Alemi·Latchkey

act expands a strategy.matrix like GitHub, but every leg runs against the container image you mapped, not distinct GitHub-hosted OS images. To iterate fast you can run a single matrix combination with --matrix.

What this error means

All matrix legs behave identically under act (same image) even when they target different OSes on GitHub, or you want to run just one combination locally.

act

[CI/test-1] matrix: {os: ubuntu-latest, node: 18}
[CI/test-2] matrix: {os: windows-latest, node: 18}  # runs on the same linux image under act

Common causes

One image backs every matrix leg

act maps labels to images; a windows-latest leg still runs on the linux image you mapped, so OS-specific behavior is not reproduced.

Running the full matrix is slow locally

Every combination runs sequentially on your machine, which is far slower than GitHub-hosted parallelism.

How to fix it

Filter to one matrix combination

Use --matrix key:value to run a single leg while iterating.

Terminal

act -j test --matrix node:18

Validate other-OS legs on GitHub

Because act runs Linux images, verify Windows or macOS matrix legs on GitHub-hosted runners.

How to prevent it

Use --matrix to iterate on one leg locally.
Reserve non-Linux OS matrix legs for GitHub-hosted runners.
Do not assume act reproduces per-OS matrix behavior.

Frequently asked questions

What causes "matrix expansion differs under act"?

act maps labels to images; a windows-latest leg still runs on the linux image you mapped, so OS-specific behavior is not reproduced.

How do I fix matrix expansion differs under act?

Use --matrix key:value to run a single leg while iterating.