Matrix jobs need separate evidence, not just separate runners
A museum website validates captions in several languages and formats during pull requests. A matrix workflow is convenient because each combination can run independently, but the checks become hard to audit if every job writes qa-report.json with the same upload-artifact name. A green overall job label also hides which language was reviewed by which validator.
The operational question is whether the English VTT report can be distinguished from the Spanish SRT report after a rerun or matrix expansion. A stable naming convention must capture execution identity and the tested input, while human approval of translations remains outside automated validation.
Understand strategy.job-index and strategy.job-total
GitHub documents the strategy context for jobs running with a matrix. strategy.job-index is a zero-based number identifying the current matrix job: the first index is 0, not 1. strategy.job-total gives the total number of jobs and is not zero based; for a matrix of four jobs the total is 4.
These are context expressions, such as ${{ strategy.job-index }}, not predefined environment variables named STRATEGY_JOB_INDEX. They can be interpolated in workflow keys where the context is available. A generated index is useful for differentiating jobs inside an execution, not as a permanent identity for a locale across future matrix edits.
Choose the right uniqueness scope for an artifact
An index alone may distinguish simultaneous jobs inside one matrix, but index 0 will exist again in the next workflow run. Add an execution identifier such as github.run_id and, where reruns matter, github.run_attempt to the artifact naming scheme. Include the input locale or format as readable metadata rather than forcing auditors to reconstruct it from a number.
One illustrative filename pattern is captions-${{ github.run_id }}-${{ github.run_attempt }}-${{ strategy.job-index }}.json. Its contents should also include the validated source commit and requested locale. File names are an organizational control, not proof that a source check was actually performed or approved.
Distinguish the index from matrix values
The matrix context exposes the combination for the current job, such as matrix.locale or matrix.format. That semantic value is what the report should say it checked; the numeric job-index only helps avoid collisions. When the workflow is changed to add a language, an index may point to a different combination than it did previously.
For example, a sequence that once had English at index 1 might assign a different language at index 1 after a new matrix include entry. Avoid audit systems that store only the index and assume it always means English. Keep the matrix values and the commit SHA as explicit report fields.
Make a process map for a caption QA matrix
Begin with the approved test matrix, expand each job, run the validator against the checked-out source, and store its distinct report. The illustrative process image shows three parallel reports converging into an editorial summary without suggesting that the summary itself is a human sign-off.
Do not have jobs write to the same mutable remote report path unless the receiving service handles concurrent updates safely. Local workspaces generally isolate matrix jobs, but artifact upload naming and a central release dashboard still need names that prevent accidental replacement or confusion.
Separate artifact availability from approval status
A produced JSON file may prove a validator ran, but its result may be fail, skipped or incomplete. Define expected fields for schema version, validator version, target locale, source commit, issue counts and whether the run was interrupted. A report that lacks a critical field should not be promoted to a release-ready artifact.
Build the release summary only from expected matrix combinations. If a job is canceled by fail-fast behavior or a matrix condition, the summary should identify the missing evidence rather than treating an absent report as a passing check. This is particularly important when public notices require every authorized language.
Protect workflow expressions and file names
GitHub expressions are evaluated by the workflow engine, but user-controlled text can still become hazardous when placed unquoted into a shell command. Treat pull-request titles, branch names and free-form locale labels as untrusted; pass them via safe environment mappings and validate allowed characters before writing paths.
Do not embed secret values, transcript contents or private donor information in artifact filenames. Reports may be accessible to more repository collaborators than the original source files, depending on repository permissions. Restrict retention and artifact sharing according to the organization’s data-handling rules.
Compare three report naming states
The first state uploads all jobs under a single name and risks collision or ambiguous evidence. The second adds job-index, preventing a clash within the current matrix but not across different workflow runs. The third combines execution and matrix identity, with readable test values stored in the report itself.
These states are conceptual examples, not screenshots of a GitHub run or proof of actual artifact behavior in a particular repository. The goal is to make report provenance reconstructable under a changed matrix, rerun, or failed job, while preventing an automated validation result from becoming a silent curatorial approval.
Test matrix changes as well as ordinary success
Use fictional caption fixtures to exercise two locales, then add a third. Confirm all expected reports have unique names and a correct zero-based index. Trigger an illustrative rerun and verify its attempt identifier makes the new output distinguishable from the earlier attempt.
Also test a failed validator and a skipped matrix job. The release process must flag the missing or failed evidence and retain links to the specific workflow run. Do not publish a transcript merely because every completed artifact happens to have a report file.
Keep the source of truth outside the report name
A responsible handoff records the workflow run, attempt, matrix combination, source commit, validator version and editorial disposition. The job index is one useful part of that trace, but it cannot assert accuracy of translated place names, accessibility of cue timing or permission to share the recording.
This is a source-checked design walkthrough based on GitHub documentation. We did not execute workflows, upload artifacts, inspect a private repository or benchmark jobs. Confirm the available contexts in your workflow syntax and verify artifact action versions before implementing the example in production.
How We Research
For this November 11, 2026 desk review we checked named primary documentation: GitHub Actions contexts reference; GitHub workflow syntax for a matrix; GitHub using a matrix for jobs. We compared the vendor-defined fields and limits with a fictional museum workflow, identified states that the API cannot prove, and designed original diagrams to show the boundaries. We did not access a live customer account, upload or modify files, run API calls, inspect private records, verify service performance, or claim empirical success rates. Preview features, permissions and product behavior can change; confirm current release notes, your organization’s contracts, and human legal or editorial approval before deploying.
Frequently Asked Questions
It begins at 0; GitHub documents the first matrix job as index 0.
No. It is the total job count, such as 4 for four matrix jobs.
No. Matrix changes can change the numeric position, so record matrix values and the source commit too.
No. Include run identity and attempt identity when reports from multiple executions may coexist.
Not automatically. Validators provide evidence; editorial, accessibility and rights approvals remain separate.