The commit being checked is not the whole proof
A fictional museum publishes caption files for an accessible exhibition site. Its pull request CI checks a proposed text change, but the release record only stores the repository SHA. After the workflow definition changes, reviewers cannot tell which QA script and approval gates actually ran. GitHub Actions exposes GITHUB_WORKFLOW_SHA as the commit SHA for the workflow file. Record it as a separate provenance field, not as a synonym for GITHUB_SHA, which identifies the commit associated with the triggering event under event-specific rules.
Collect the workflow identity with the run identity
Capture GITHUB_WORKFLOW_SHA, GITHUB_WORKFLOW_REF, repository ID, event name, GITHUB_RUN_ID and GITHUB_RUN_ATTEMPT with the tested content identifier. The ref points to a workflow path and reference; the workflow SHA tells you the workflow file’s commit. A run ID stays the same across retries, while the attempt number changes. That distinction lets reviewers reconstruct which workflow version made a specific report without collapsing two attempts into one record. Store these values as metadata and avoid printing the entire github context because it can contain sensitive information.
Interpret GITHUB_SHA according to the event
For some pull request events, GITHUB_SHA can represent a test merge commit rather than the head commit in the contributor’s branch. The prior archive article on GITHUB_SHA addresses that event-specific distinction; this guide answers a different question: which workflow definition produced the test? Keep source commit, tested merge commit and workflow file commit in separate columns. Do not sign a release merely because two SHA strings look similar. A review record should name the content artifact and the verification procedure with its exact code revision.
Design a compact provenance record
Use a report header that names the repository identifier, workflow path/ref, workflow SHA, event, run ID, attempt and tested content SHA. Add the caption artifact’s own digest when a digest is generated by a trusted build step. This evidence model helps later investigators compare the published file to the file CI actually checked. Keep untrusted branch names and event-payload text out of shell commands; quote paths and use structured environment variables. No part of a commit hash, by itself, provides a rights clearance or quality judgment.
Check the workflow definition at the recorded revision
When a report is questioned, review the workflow YAML at the recorded workflow SHA and ref, including reusable workflows, action versions and required checks. The workflow hash locates the definition; it is not an attestation that every third-party action or dependency was pinned or secure. Inspect permissions for GITHUB_TOKEN, trigger types and whether a pull_request_target workflow could run untrusted code. A trusted reviewer should be able to identify the actual release gate even if the default branch later contains a different workflow file.
Guard against mutable tags and external actions
A report can contain a precise workflow SHA while still relying on actions referenced by mutable tags or unreviewed scripts downloaded at runtime. GitHub recommends security hardening that includes least privilege, review of untrusted input and appropriate action pinning practices. Record key external action versions and the environment when required by the release policy. Do not confuse the provenance of the YAML with the provenance of every executable it invokes. The caption pipeline must also protect repository secrets from code contributed by untrusted pull requests.
Avoid granting approval from environment variables
These GitHub variables are evidence labels, not authorization checks. A workflow could record a correct SHA and still run an incomplete caption validator or approve changes without a human sign-off. Keep publication permission tied to branch rules, authorized maintainers and an explicit release checklist. Compare output against accessibility acceptance criteria such as language coverage, meaningful speech labels and timing rules, with source files preserved for review. Treat CI failures as blocks, not as optional warnings that a hash can override.
Plan retention outside ephemeral Actions logs
Workflow logs and uploaded artifacts have retention policies and may expire before a museum needs its accessibility evidence. The release process should copy the minimal approved report and artifact digest to a controlled long-term evidence store under the institution’s retention policy. Avoid archiving full event payloads, tokens or personal information. Refer to the current GitHub retention settings when choosing how long run records remain available. A release record that depends solely on an expiring console page is weak even if every SHA was captured accurately at run time.
Reconstruct a release in an acceptance exercise
Use two synthetic workflow revisions and one caption sample in a private test repository. Verify that report metadata distinguishes source content, workflow file version and retry attempt even when filenames match. Then change a third-party action reference and confirm reviewers can identify the changed dependency separately. These are suggested tests, not claims that GitHub was run for this article. A complete audit should let a reviewer say which content was checked, by which workflow revision, under what event and who separately approved its public release.
How We Research
For this guide, we compared these official primary sources, consulted on November 10, 2026: GitHub default variables reference; GitHub contexts reference; Security hardening for GitHub Actions. We traced the named API field or operation to its documented behavior, separated guaranteed platform semantics from hypothetical museum workflows, and checked for related topics already in the LabFin archive. No production API calls, live benchmarks, measured performance, commissioned user trials or real museum data were involved. Names, statuses and diagrams are instructional examples; verify the version, access model and retention settings in your own environment before applying the procedure.
Frequently Asked Questions
GitHub documents it as the commit SHA for the workflow file.
No. GITHUB_SHA tracks the event-associated commit, while GITHUB_WORKFLOW_SHA identifies the workflow file revision.
Keep GITHUB_RUN_ID and GITHUB_RUN_ATTEMPT with the workflow SHA; the attempt changes on rerun.
No. Review external action references, permissions and runtime downloads independently.
No. Release authorization requires trusted approvals and actual caption QA results beyond any environment variable.