In a GitHub Actions strategy matrix, what do include and exclude actually do?

## The cross product strategy: matrix: os: [ubuntu-latest, windows-latest, macos-latest] java: [17, 21] Each key holds an array; the matrix expands to every combination — six jobs here. Each job is a copy of the job definition with `matrix.os` and `matrix.java` bound to its own values, usable anywhere expressions are allowed, including `runs-on: ${{ matrix.os }}` and in step inputs. A single workflow run is capped at 256 jobs generated by one matrix, which is a real ceiling for large multi-dimensional matrices. ## exclude `exclude` removes combinations. Every key/value pair listed must match for a combination to be dropped, and a partial specification removes every combination that matches it: exclude: - os: macos-latest java: 17 # drops exactly one job - os: windows-latest # drops every windows job This is how you express "this pairing is unsupported" without restructuring the arrays. ## include `include` is the more subtle one, and the rule has two branches. **Merging into existing combinations.** If an include object's keys that also exist in the matrix all match a generated combination, its remaining keys are added to that job — as long as they do not overwrite an original matrix value: include: - os: ubuntu-latest java: 21 coverage: true # only that one job gets matrix.coverage An object with no matrix keys at all merges into **every** combination, which is a handy way to add a shared value. **Appending new combinations.** If the object cannot be merged — typically because it sets a matrix key to a value not in the original array — it becomes an additional job: include: - os: ubuntu-latest java: 25 # 25 is not in the java array: a seventh job This is the standard way to add one experimental leg without widening the product. ## Order of processing Exclusions are applied to the expanded product first; inclusions are processed afterwards. The practical consequence is that an `include` can add back a combination that `exclude` just removed, which reads as contradictory in a diff but is well-defined. Interviewers ask because engineers routinely assume the opposite ordering and then cannot explain why an excluded combination still ran. ## Using a matrix without a matrix `include` alone — with no array keys — is a legitimate and common pattern: it defines an explicit list of job configurations rather than a product. strategy: matrix: include: - os: ubuntu-latest java: 21 label: fast - os: windows-latest java: 17 label: compat This is clearer than a product plus a wall of exclusions when the supported combinations are sparse. ## Practical notes - The generated jobs get distinct names built from their matrix values, which is what makes a failing leg identifiable in required-check lists; renaming keys changes those job names. - Matrix values feed cache keys too — include the values that affect dependencies, or matrix legs will fight over one cache entry. - Matrix values are also available in `if:` conditions, so a step can be skipped on one leg without a separate job. - Keep the product honest: every combination is a full job with its own checkout, setup, and dependency install, so an extra dimension multiplies queue time and cost rather than adding it. ## The concise answer "The arrays expand to the cross product; `exclude` prunes combinations from it; `include` either enriches matching combinations or appends new ones; and because exclude runs first, include can put a combination back."