When to opt in
A matrix job is a good fit when:- Its variations do different work. Each runs on a different OS, runtime version, test suite or package group, so a change can break one and not the others.
- It is expensive. Skipping part of it saves real runner time.
Choose the keys to group by
This is the choice that matters most. You pick one or more of the matrix’s keys. Variations that share values for those keys form a decision group, and each group gets its own run or skip decision, learned from that group’s own history. That history is only useful if each group does the same work from one run to the next. Ifsuite=frontend always runs the frontend tests, its history says
how often a change like this one breaks the frontend tests. If it runs a
different set of tests each time, its history says nothing, and its decisions
will be poor.
Some more guidance:
- Keys you don’t pick run together. In a matrix of
os×node, grouped byos, the Linux variations for every Node version run or skip together. - Fewer keys mean larger groups, which learn faster. A group needs about 10 runs in the past week before it is decided on its own history. Until then it follows the decision for the whole job.
- Start with the key that names what breaks independently. If the macOS build fails for reasons the Linux build never sees, group by OS.
Opt a job in
1
Open the job's settings
In Dynamic CI → Configuration,
open the Jobs tab and click the matrix job to expand it. A matrix job’s
Schedule column shows how it is grouped, such as matrix: Group by none.
2
Pick the keys under Group by
The Matrix variations section lists the job’s variations under
Decision groups. With no key picked, the job is one group,
All Variations: every variation runs, or none does.Under Group by, click each key to group by. The list regroups as you go,
one decision group for each value (or combination of values) of the keys you
picked. Click a key again to unpick it. View YAML opens the workflow file
with this job’s matrix highlighted.
3
Set up your CI
- GitHub Actions: the matrix reads which variations to run from the Dynamic CI job. See Matrix jobs on GitHub Actions.
- Buildkite: no pipeline change beyond the plugin version. See Matrix steps on Buildkite.
4
Save
In an Enforced repository, the next push is decided by group. In
Learning mode, Dynamic CI records a decision for each group and skips
nothing, so you can see how the grouping would behave first.