exclude entry partially matches, and only then applies include. An include entry is merged into every remaining original combination it can join without changing one of that combination's matrix values; if it can join none, it becomes a job of its own. The preview shows which happened for each entry, the job names, and the count against the 256-job limit.A WebKit job on Windows takes nine minutes while every other browser job takes four. Its log shows the whole Playwright suite running in one go. Nobody removed the shard from the command; the job simply has no shard value, because the include entry that created it never set one, and --shard= with nothing after it is not an error. Two other jobs upload a coverage report that was meant to come from one. All of this was decided by the matrix before a runner started, and all of it can be seen without running the workflow.
Three operating systems, three browsers and two shards, with two exclusions and three include entries, each with a comment saying what its author wanted:
\n\njobs:\n e2e:\n runs-on: ${{ matrix.os }}\n strategy:\n fail-fast: false\n max-parallel: 6\n matrix:\n os: [ubuntu-latest, windows-latest, macos-latest]\n browser: [chromium, firefox, webkit]\n shard: [1/2, 2/2]\n exclude:\n - os: windows-latest\n browser: webkit\n - os: macos-latest\n browser: firefox\n include:\n # Collect coverage on one job\n - os: ubuntu-latest\n browser: chromium\n coverage: true\n # Add a Node 24 canary job\n - os: ubuntu-latest\n browser: chromium\n node: 24\n # Run WebKit on Windows once after all\n - os: windows-latest\n browser: webkit\n steps:\n - uses: actions/checkout@v6\n - uses: actions/setup-node@v7\n with:\n node-version: ${{ matrix.node || 22 }}\n - run: npx playwright test --project=${{ matrix.browser }} --shard=${{ matrix.shard }}This is the preview's built-in sample, so Load sample reproduces it. The summary reads Jobs 15 / 256, Product 18, Excluded 4, Added by include 1, fail-fast false and max-parallel 6. The order panel and the rows that matter:
\n\nexclude[0] {\"os\":\"windows-latest\",\"browser\":\"webkit\"} removed 2 combinations\nexclude[1] {\"os\":\"macos-latest\",\"browser\":\"firefox\"} removed 2 combinations\ninclude[0] {\"os\":\"ubuntu-latest\",\"browser\":\"chromium\",\"coverage\":true} merged into 2 jobs\ninclude[1] {\"os\":\"ubuntu-latest\",\"browser\":\"chromium\",\"node\":24} merged into 2 jobs\ninclude[2] {\"os\":\"windows-latest\",\"browser\":\"webkit\"} added as a new job\n\n# Job name shard coverage node From\n1 e2e (ubuntu-latest, chromium, 1/2) 1/2 true 24 product, extended by include[0], include[1]\n2 e2e (ubuntu-latest, chromium, 2/2) 2/2 true 24 product, extended by include[0], include[1]\n15 e2e (windows-latest, webkit) - - - added by include[2]None of the three comments describes what its entry does. Coverage runs on two jobs. No canary job exists; the two existing Ubuntu Chromium jobs quietly moved to Node 24. And the Windows WebKit job has no shard.
\n\nGitHub's workflow syntax reference states it in two sentences. The key and value pairs in an include object are added to each matrix combination \"if none of the key:value pairs overwrite any of the original matrix values\", and an object that cannot be added to any combination becomes a new combination. Original values are protected; values an earlier include added are not. The how-to page adds the detail that catches people twice: include entries are compared only with the original combinations, so a later entry is never merged into a job an earlier entry created.
\n\nRead the three entries against that rule.
\n\ninclude[0] names os and browser but not shard. An entry that leaves a variable out does not conflict with any value of it, so both shards of Ubuntu Chromium qualify and both get coverage: true. The preview's note says exactly that: the entry \"is merged into 2 combinations, because it does not name shard\".
include[1] has the same problem with a worse result. node is not a matrix variable, so setting it can never overwrite an original value, and the entry joins the same two jobs. An include only creates a job when it conflicts with every remaining combination. This entry conflicts with none, so the canary was never a separate job, and the jobs that were supposed to stay on Node 22 now install 24.
include[2] would have joined the two Windows WebKit combinations, but exclude removed them first. With nothing left to join, it becomes a new combination containing only os and browser. The syntax reference documents this ordering deliberately: \"All include combinations are processed after exclude\", which is how you add back something exclude removed. What it does not do is copy the variables the entry left out.
The new job has no shard key. GitHub's contexts reference says that dereferencing a property that does not exist \"will evaluate to an empty string\", so the run step becomes npx playwright test --project=webkit --shard=. In Playwright 1.62.1, resolveShardOption in packages/playwright/src/cli/testActions.ts starts with if (!shard) return undefined: an empty value means no sharding, with no warning. Listing this site's own Playwright suite shows the effect:
npx playwright test --list --shard=1/2 # Total: 413 tests in 12 files\nnpx playwright test --list --shard= # Total: 825 tests in 12 files\nnpx playwright test --list # Total: 825 tests in 12 filesA value Playwright rejects, such as --shard=all, would at least fail the job. The empty string passes, which is why the preview reports a created job that lacks a matrix variable as a warning rather than a note: \"It has no shard, so matrix.shard is an empty string in this job.\"
Each fix comes from the same rule. To target one job, name every matrix variable. To force a new job, give it a value of a matrix variable that no remaining combination has.
\n\n include:\n - os: ubuntu-latest\n browser: chromium\n shard: 1/2\n coverage: true\n - os: ubuntu-latest\n browser: chromium\n shard: 1/1\n node: 24\n - os: windows-latest\n browser: webkit\n shard: 1/1The preview now reports 16 jobs. include[0] is merged into job 1 only. include[1] becomes job 15, e2e (ubuntu-latest, chromium, 1/1, 24), because \"No original combination has shard: 1/1 (the matrix has 1/2, 2/2), and original values are never overwritten.\" include[2] becomes job 16, e2e (windows-latest, webkit, 1/1), with a note that it matches an exclude entry and runs anyway. Playwright accepts 1/1: the same validation only requires the current shard to be between 1 and the total, and --list --shard=1/1 lists all 825 tests.
The shard: 1/1 trick works here because shard already exists. When no variable has a spare value, the documented pattern is a single-value variable such as experimental: [false], with the extra job's entry setting experimental: true. The cost is that the value appears in every job's name, so , false is appended to each original job.
The job names come from GitHub's behaviour rather than its documentation, which does not describe them. The preview's rules were taken from the names GitHub assigned in public workflow runs on 1 October 2026, read from the REST API's list-jobs endpoint and checked against each run's workflow file:
\n\nname, or a name without an expression, gets the original matrix values in brackets, in matrix order: Unit tests (macos-latest, 3.10) in a pyvisa run.coverage: true and the job is still called test (1.27).java, experimental, os produced build (27-ea, true, ubuntu-latest), while the original jobs read build (ubuntu-latest, 8, false).flags value was \"\" is Build (ubuntu-latest, stable, false).name containing an expression is used as written with nothing appended.Two consequences are worth checking for. Because added keys are hidden, the original job and its coverage twin can look identical. A jwt-auth run shows the harder version: an include that differed from an existing job only in coverage: xdebug against coverage: [none] became a 45th job, and its name expression did not mention coverage, so two jobs are named PHP8.5 - L12.* - prefer-stable. The preview flags duplicate names. The same run names its PHP 8.0 jobs PHP8, because unquoted 8.0 in YAML is the number 8. 3.10 becomes 3.1 the same way, which is why version lists are quoted. The preview reports each number whose text changed on parsing, and separately warns about any exclude entry that matched no combination.
Matrices built from ${{ fromJSON(needs.setup.outputs.matrix) }} are common, and their values exist only during a run. The contexts reference lists github, needs, vars and inputs as available to jobs.<job_id>.strategy; none of them exists in a browser. When the whole matrix, a variable's list, or the include or exclude list is an expression, the preview gives no count. When an expression is one value inside a list, it keeps the text, counts it as one value and marks the result approximate, because the job count is only right if it really is a single value.
It also refuses three things GitHub does not document, instead of picking an answer: two variables whose names differ only in case (the syntax reference says names are case-insensitive, but not how two such lists combine), a YAML merge key, and an empty list. Object values are compared by deep equality in include and exclude, and are printed as JSON where they appear in a name, since GitHub's own rendering of them was not observed. The tool does not check runner labels, concurrency groups, continue-on-error, or whether a value works in your steps; that is how --shard= slipped through in the first place.
Can exclude remove a job include added? No. exclude runs first and only sees the product, so an exclude entry naming a key that only include sets matches nothing. The preview warns about that entry.
\n\nDoes the 256-job limit count before or after exclude? The syntax reference says a matrix \"will generate a maximum of 256 jobs per workflow run\", which is the generated list, after exclude and include. A product of 300 that excludes trim to 200 is within it. The preview counts the final list and stops enumerating at 20,000 combinations.
\n\nDoes max-parallel change the count? No. It caps how many of the jobs run at once; without it GitHub runs as many as runners allow. fail-fast defaults to true, which cancels in-progress and queued matrix jobs when one fails. The sample turns it off so one browser's failure does not hide another's.
How many combinations do I need? Usually fewer than the product. The same boundary-row reasoning in choosing JUnit parameter rows without a matrix explosion applies to CI dimensions, and if the shards feed a flake gate, failing CI on flaky Playwright tests covers merging their reports first. To see how a single value parses before it reaches the matrix, the YAML Formatter shows its JSON type.
\n\nPaste the workflow with your largest matrix into the preview. For every include entry, compare the order panel's \"merged into N jobs\" or \"added as a new job\" with the comment or commit message that introduced it, and fix any entry where they disagree by naming every matrix variable or giving it a conflicting value. Treat each warning that a created job lacks a variable as a bug until a step proves it handles the empty string. Copy the Markdown table into the pull request that changes the matrix, so the reviewer sees the job list instead of inferring it.
\n\njobs.<job_id>.strategy.matrix: the 256-job limit, case-insensitive variable names, the include rule, partial-match exclude, and include after exclude.strategy.3.10 resolve to floats under the core schema.testActions.ts: resolveShardOption returns no shard for an empty value and validates current/all.--shard=x/y option and merging sharded reports.