Why the friendly build counter is not an audit key
A museum maintains subtitle files for an exhibit video and runs automated caption checks on every proposed change. An easy release label is the workflow run number, such as Caption QA #42. That number is useful for humans scanning a release list, but it is not a globally unique evidence identifier and does not distinguish an original attempt from a rerun.
If two workflows use similar names or a repository is transferred, a standalone counter becomes a weak reference. Keep a display label and a more complete provenance record with the repository, workflow identity, run ID, attempt and source revision. The automation can check formatting, while accessibility and editorial approval remain separate human responsibilities.
What GITHUB_RUN_NUMBER actually means
GitHub documents GITHUB_RUN_NUMBER as a number for each run of a particular workflow in a repository, beginning at 1 and increasing with each new run. It does not change when that run is rerun. This is a workflow-local counter in the repository, not the ID of the run resource and not a claim about how many accessibility reports succeeded.
Use it as an understandable sequence in reports or internal dashboards. Avoid deriving a public-release authorization from the value, and do not expect run number 42 in one workflow to refer to the same commit as run number 42 in another workflow. A failed run can also consume a number.
Compare number, ID and attempt
GITHUB_RUN_ID identifies a workflow run within a repository and remains the same across reruns. GITHUB_RUN_ATTEMPT starts at 1 and increments each time the same run is rerun. Together with the workflow identifier and commit SHA, these fields tell reviewers which attempt produced a report. GITHUB_RUN_NUMBER alone cannot distinguish a rerun of a failed caption checker from its earlier result.
A sensible private artifact label might include a sanitized repository key, workflow key, run ID and attempt; reserve the smaller run number for the user-facing caption-review index. Do not include branch names or pull request titles directly in shell commands. Event metadata can be untrusted input and should be treated as data rather than executable syntax.
Capture the source commit that was actually checked
The caption report should identify which subtitle files and video master version were analyzed. GITHUB_SHA refers to the commit that triggered a workflow under the event-specific rules GitHub documents; pull-request workflows may reference a synthetic merge commit rather than the contributor’s head commit. Record the checked-out revision, the event type and relevant source paths when provenance matters.
An accession display label, such as EX-082, is not enough to identify a subtitle revision. Include a checksum of the exported caption file and the test configuration version. If the editor uploads a different subtitle file after the CI run, its previous green status should not be reused without validation against the replacement content.
Design names that survive reruns and comparisons
Consider a report path containing a workflow key, run ID, attempt and language code. It stays distinct across retries and across parallel language reviews while remaining easy to correlate with GitHub. If a new run reuses the same human-friendly caption title, its artifact is still separable by execution identity.
Limit artifact names to a safe character set and use normalized, validated language identifiers rather than arbitrary contributor strings. Upload only the review materials permitted by organizational policy. A report can contain private transcript passages or accessibility notes, so uploading it to a repository with broad artifact access may be inappropriate.
Keep the report separate from the release decision
An automated check can confirm timing syntax, encoding, line lengths and presence of required files, but it cannot by itself certify names, sign-language access, sound descriptions or accurate translation. A release ledger should record the actual test output, its hash, source reference, reviewer, and decision status. Passing CI is a prerequisite for review, not authority to publish.
If a workflow is rerun after an infrastructure failure without changing the source, reviewers should still know the attempt that produced the accepted result. If the source or configuration changed, treat the subsequent evidence as a new basis for editorial review instead of replacing old evidence invisibly.
Handle workflow names and file paths carefully
GitHub documents GITHUB_WORKFLOW_REF and GITHUB_WORKFLOW_SHA for workflow provenance, and GITHUB_SERVER_URL for building links under GitHub Enterprise. A report referring only to a friendly workflow name can become ambiguous after a rename. Build links with validated server and repository context, or use the supported API to retrieve run metadata.
Never embed a secret or full github context dump into a public accessibility report. GitHub warns that contexts can contain sensitive information and untrusted fields. Capture the limited allowlisted fields needed for traceability, and give the release reviewer an authenticated route to the private detailed logs when necessary.
Compare the three caption-review identities
The illustration contrasts a bare run number with no repository or source context, a repeated run with a new attempt but the same run ID, and a full identity tied to a caption artifact digest. These are sample labels, not observed GitHub runs. The third state still needs a human approval stage before visitor-facing subtitles are released.
The visible report should not imply that a higher run number equals better captions. The counter indicates execution sequence, not quality or completeness. A different video master can make an older artifact irrelevant even when every automated test was green.
Practice failure paths with synthetic caption files
Create an internal test workflow using sample subtitle text. Trigger one successful run, cause a controlled validation failure, and rerun that same run. Inspect the differences among RUN_NUMBER, RUN_ID and RUN_ATTEMPT, then verify that artifacts remain distinguishable and that the approved source revision matches each result.
Do not run experiments with protected visitor recordings or copyrighted media for which repository storage has not been approved. Review artifact-retention settings separately: keeping a link in a ledger does not mean the underlying CI artifact remains retrievable forever. Preserve required evidence under the institution’s controlled retention policy.
Build a durable caption QA handoff
Before approving the subtitle release, require a checked source SHA, specific report identity, passed checks, complete language coverage, reviewer acknowledgment and a rights-safe storage destination. Record the human-readable run number as a convenience next to stronger identifiers, not instead of them. Reject a release that points to an unverified rerun or mismatched caption digest.
This explanation is grounded in GitHub documentation and a hypothetical museum workflow. We did not execute CI jobs, inspect a repository or measure false-positive rates. Confirm the current GitHub event semantics, artifact permissions and your accessibility policy before operational adoption.
How We Research
For this November 11, 2026 desk review we compared authoritative documentation: GitHub Actions variables reference; GitHub Actions contexts reference; GitHub upload artifact guidance; GitHub secure use reference. We reviewed the named field definitions, failure paths, and operational limits against a fictional museum workflow, and drew original conceptual illustrations. We did not run API requests, inspect customer accounts, measure service performance, approve any copyright license, or verify live collection data. Documentation, plan availability, security settings and preview status can change; confirm the current service reference and your organization’s legal and editorial policies before production use.
Frequently Asked Questions
No. GitHub defines it as a per-workflow sequence within a repository; another workflow can have the same number.
No. GITHUB_RUN_NUMBER and GITHUB_RUN_ID remain unchanged for that run; GITHUB_RUN_ATTEMPT increases.
Use repository and workflow context, RUN_ID, RUN_ATTEMPT, source SHA and a report digest where appropriate.
No. Human review must still verify meaning, timing, accessibility needs and the exact released media version.
Do not do so without validation and safe quoting. Treat event-derived metadata as untrusted input.