GitHub Actions Matrix Exclude: Partial Match Explained

DEV Community

GitHub Actions matrix exclude not working, and the partial match

GitHub Actions matrix exclude not working is most often the opposite complaint from the one people arrive with: the entry matched more combinations than intended, not fewer. An exclude entry is a partial match, so naming one key removes every combination that agrees on that key, whatever the other keys hold. An exclude entry naming one key of two constrains only that key. Both combinations that agree on it are removed. What this error means The job count is wrong and nothing is annotated. Either several legs you wanted are gone, which is the partial match doing exactly what it is specified to do, or a leg you tried to remove is still there, which usually means it was not in the cross product to begin with. The tell in both directions is that the run succeeds and the job list is simply a different length than the arithmetic in your head. There is no message to search for, because nothing went wrong from the builder point of view. ```Illustrative matrix fragment, not a log line: this outcome produces no message matrix: os: [ubuntu-latest, windows-latest] node: [18, 20] exclude: - node: 18 two jobs remain, not three

Common causes

The exclude entry names fewer keys than the combination has

The dominant cause. One key named means one comparison, and every combination agreeing on that key is removed regardless of the others, which is usually a whole slice rather than a single job.

The entry names a value that is not in the cross product

A filter that matches nothing removes nothing, and it is not an error. This happens when a matrix value changes and the exclude entry describing it is not updated in the same change.

The job being excluded was created by an include entry

Configurations that include adds are produced after the exclusion pass has finished, so they are never tested against exclude at all. The only way to stop one is to change the include entry.

The matrix was changed and the count was never rechecked

In our experience this is how a wrong count survives for months. Adding one value to a dimension multiplies the product and can move which combinations an existing partial entry removes.

How to fix it

Name every key needed to identify the combination

To remove exactly one job, the entry has to constrain every dimension. Anything less is a slice, and the number of keys you name is the number of comparisons the builder creates.

```.github/workflows/ci.yml
matrix:
os: [ubuntu-latest, windows-latest]
node: [18, 20]
exclude:
- os: windows-latest
node: 18
Print the matrix context and count the legs Add a step that serializes the matrix context to the log. Set fail fast to false so a single failure does not hide the rest of the expansion. Run it and compare the number of legs against the number you expected. Leave the step in place for whoever edits the matrix next. Change the include entry rather than excluding what it adds A configuration that only exists because include created it cannot be removed by exclude, because it is produced after the exclusion pass. Edit or delete the include entry instead. Build the matrix from include entries when the set is small If you want five specific combinations, list five include entries and define no dimensions to cross. Nothing has to be subtracted, so none of the subtleties on this page applies. strategy:
matrix:
include:
- os: ubuntu-latest
node: 20
- os: windows-latest
node: 22
How to prevent it Treat the key count in an exclude entry as the width of the filter, and check it. Keep a step that prints the matrix context permanently in any workflow with a matrix. Recheck the job count whenever a dimension gains or loses a value. Prefer an explicit list of include entries when the wanted set is small. An exclude entry constrains only the keys it names The published schema says it in one line: an excluded configuration only has to be a partial match for it to be excluded. The builder implements ...

Powered by Readybot.io