GitHub Actions GITHUB_SHA: Keep PR Merge Tests Separate From Caption Source Commits

A green PR check may refer to a synthetic merge

A museum asks contributors to correct transcription captions through pull requests. The caption-review job reports a passing GITHUB_SHA and an editor assumes that identifier is the exact commit the contributor submitted. For a pull_request event, GitHub documents that GITHUB_SHA refers to the last merge commit on the pull request’s merge branch, not necessarily the head commit in the contributor’s branch. The distinction is important when storing evidence, attributing corrections, or reusing a QA result after the base branch changes. This is a hypothetical workflow and not a finding about a real GitHub repository.

Know which event created the run

Start by recording the event name, repository, pull request number when present, and the relevant checkout ref. GitHub variables have event-specific meanings, so a value that identifies a branch tip for a push can identify a synthetic merge for a pull_request run. Do not normalize every SHA to one notion of submitted source. Read the events-that-trigger-workflows documentation alongside the variables reference. A reusable workflow or manual dispatch can introduce different contexts, and missing pull-request fields should be handled explicitly rather than guessed from branch names.

Capture merge SHA and head SHA separately

For an open, mergeable pull request, GitHub describes GITHUB_REF as refs/pull/NUMBER/merge and GITHUB_SHA as the last merge commit on that branch. The head commit is available through github.event.pull_request.head.sha. Record both values when the audit needs to distinguish what would be integrated with the base branch from what the contributor authored. Label them tested_merge_sha and submitted_head_sha or another unambiguous pair, rather than storing only sha. The values may not represent the same tree and can change as the PR or base advances.

Choose the checkout strategy for the question

A caption integration test normally wants to see whether the proposed changes work with the destination branch, so the default merge-ref checkout can be appropriate. A provenance check may instead inspect the exact contributor head commit, using an explicitly selected ref and the documented pull request head SHA. These tests answer different questions; one cannot be substituted for the other without changing the claim in the report. If untrusted code comes from a fork, keep secrets and write permissions away from that execution path. Merely selecting a SHA does not make checked-out code trustworthy.

Attach QA artifacts to the correct source revision

A meaningful caption QA report includes repository identity, pull request number, event name, run ID, run attempt, tested merge SHA, submitted head SHA, base ref, and check definition revision. Save only the minimal evidence needed to reproduce the conclusion. A checksum of the caption files themselves can also help if the workflow transforms input during testing. Avoid copying donor-provided transcripts or private editorial notes into public artifact logs. A passing result should state exactly which source and combined state it covered, especially if the merge commit is regenerated after an update.

Compare head-only and merge-context results

Consider a contributor who corrects a caption file while a curator simultaneously changes a glossary on the base branch. The head-only check may pass against an older glossary, while the merge-context check detects a terminology conflict. In the opposite direction, merge-context results may differ from the contributor’s committed tree because merged dependencies or configuration affect the test. Represent these as two labeled comparisons rather than using one green badge to imply both passed. A synthetic diagram is useful for explaining the distinction but is not a measured GitHub run or a promise that a merge will succeed.

Guard shell usage and permissions

Never interpolate untrusted PR titles, branch names, or other event metadata directly into shell commands. Treat event JSON as data and use safe environment variables or a checked scripting interface. Checkout actions should run with least-privilege tokens; a PR from a fork may contain untrusted scripts. GitHub’s pull_request_target event has different privilege implications and should not be swapped in simply to gain access to secrets. Verify third-party action versions and avoid persisting tokens into a repository workspace that untrusted steps can read. A correct SHA is only one part of a defensible CI boundary.

Invalidate stale proof when commits change

If the contributor pushes another commit or the base branch moves, determine whether the stored integration result still describes the tree about to be merged. An earlier tested merge SHA may no longer be current; even a head SHA that has not changed can be combined with a different base. Require fresh checks based on branch protection and organizational policy. Preserve the history of old runs rather than silently overwriting their identifiers. An editorial reviewer should distinguish historical evidence of a prior run from a current approval to publish captions.

Write a release gate that states the tested object

Before a museum caption correction is accepted, verify the intended repository, PR, current head, current base, tested merge or head mode, check status, and human approval. The approval record should include an exact commit or tree reference and the scope of tests performed. If a job reports only GITHUB_SHA, document whether its event made that a merge commit or a branch commit before treating it as author attribution. Keeping the two identifiers visible makes a small CI workflow more accurate, reduces misleading audit records, and avoids treating a passed integration check as proof of caption truth.

Related guides

• GitHub Actions GITHUB_WORKFLOW_SHA: Prove Which Caption-QA Workflow Ran
• GitHub Actions GITHUB_GRAPHQL_URL: Query Caption PR Metadata Without Hardcoding a Host
• GitHub Actions PostgreSQL Service Containers: Test Museum Imports Without Touching Production

How We Research

We reviewed the current official references: GitHub Actions variables reference; GitHub Actions workflow events. Our editorial method compared the documented API contract, configuration boundaries, and known limitations with the hypothetical museum use case described above. We distinguished software behavior from source accuracy, legal permissions, cost acceptance, and publication approval. We did not call a production API, measure a live system, inspect a customer account, or obtain the imagined collection records. Diagrams are original educational illustrations and show no measured provider output. Readers should confirm model or API-version support, live permission settings, and current organizational policy before using these instructions.

Frequently Asked Questions