MatrixMap

Visualize and expand GitHub Actions matrices directly in your browser.

Open MatrixMap · GitHub Actions matrix documentation

Matrix strategies are compact to write and surprisingly easy to misread. A small exclude can remove more jobs than expected, and include does not simply append rows—it may modify compatible original combinations or create entirely new ones.

MatrixMap makes that behavior visible before a workflow runs.

What it does

Paste a complete workflow, a strategy block, a matrix wrapper, or a raw matrix mapping. MatrixMap then:

• builds the Cartesian product in declaration order;
• applies partial-match exclude rules;
• applies GitHub-compatible include semantics;
• distinguishes base, include-modified, and include-added jobs;
• shows dimension frequencies and matrix metadata;
• warns when the result exceeds GitHub's 256-job matrix limit;
• exports final combinations as JSON;
• keeps all source text and processing inside the browser.

There is no account, backend, analytics script, cookie banner, API key, or repository connection.

Example

strategy:
  fail-fast: false
  matrix:
    os: [ubuntu-latest, windows-latest, macos-latest]
    node: [20, 22]
    exclude:
      - os: windows-latest
        node: 20
    include:
      - os: ubuntu-latest
        node: 24
        experimental: true

MatrixMap resolves this to:

6 base combinations
− 1 excluded combination
+ 1 include-added combination
= 6 final jobs

Supported input shapes

Complete workflow

jobs:
  test:
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
        node: [20, 22]

Strategy block

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]

Matrix wrapper

matrix:
  python: ['3.11', '3.12']

Raw matrix or include-only matrix

include:
  - site: production
    region: us-east-1
  - site: staging
    region: eu-west-1

Matrix semantics

MatrixMap follows the behavior documented by GitHub Actions:

1. Generate the Cartesian product of matrix dimensions.
2. Remove combinations matching every key/value pair in an exclude entry.
3. Process include entries in order.
4. Merge an include into each compatible original combination when it does not overwrite an original dimension value.
5. Allow a later include to overwrite keys added by an earlier include.
6. Add the include as a new combination when it cannot merge into any original combination.
7. Never apply later include entries to combinations created by an earlier include.

The domain behavior is isolated from the UI and covered by automated tests, including GitHub's fruit/animal include example.

Local development

Requirements:

• Node.js 22 or newer
• npm

git clone https://github.com/DarkMatterNet/matrixmap.git
cd matrixmap
npm install
npm test
npm run dev

The local preview is served at http://127.0.0.1:5173.

Useful commands:

npm run typecheck  # strict TypeScript check
npm test           # compile and run unit tests
npm run build      # create the static dist/ directory
npm run preview    # serve dist/ at port 4173

Architecture

MatrixMap intentionally has no runtime dependencies and no frontend framework.

src/domain/
  yamlLite.ts            focused YAML parser for common Actions workflows
  parseMatrixInput.ts    input-shape resolution and validation
  expandMatrix.ts        Cartesian product, exclude, and include semantics
  summarizeMatrix.ts     counts, frequencies, limits, and metadata

src/ui/
  editor.ts              input and example rendering
  results.ts             cards, table, exclusions, and context rail
  diagnostic.ts          empty and error states

src/app/
  evaluateSource.ts      pure source-to-result evaluation
  createApp.ts           browser state and interactions

TypeScript compiles to native ES modules. The build script copies those modules and static assets into dist/, which GitHub Pages can serve directly.

YAML support and limitations

The built-in parser supports the structures commonly needed to locate and expand GitHub Actions matrices:

• indented mappings and sequences;
• inline arrays and mappings;
• quoted and plain scalars;
• booleans, numbers, and nulls;
• comments;
• object-valued matrix dimensions;
• block scalar fields elsewhere in a workflow.

MatrixMap deliberately does not evaluate GitHub expressions such as ${{ fromJSON(...) }} because their values depend on runtime workflow context. It also does not act as a general-purpose YAML engine for custom tags, multiple YAML documents, or complex anchor/alias graphs.

Browser safety

GitHub allows up to 256 jobs in a matrix. MatrixMap displays a warning above that limit and caps visible result rows at 256. A separate 4,096-base-combination guard prevents accidental browser memory spikes while still explaining the computed product size.

Privacy

Everything runs locally. Pasted workflows are never uploaded or stored by MatrixMap.

Contributing

Bug reports and focused pull requests are welcome. Changes to matrix semantics should include a regression test in tests/unit/ and reference the relevant GitHub Actions behavior.

License

MIT © 2026 DarkMatterNet