A readable ref name is not a unique report key
A museum repository may generate accessibility reports for captions in several languages. Engineers sometimes put the GITHUB_REF_NAME value directly into a report filename to show which branch was checked. That looks convenient, but the variable is an event-dependent short ref name and is not globally unique. GitHub documents a special value for pull requests that have not been merged, such as 42/merge. If a script mistakes that for the contributor’s branch, a curator can review evidence attributed to the wrong source. Treat the ref name as a display hint and keep run identity and commit provenance in separate fields.
Read what GitHub defines, not what the filename suggests
GitHub defines GITHUB_REF_NAME as the short name of the branch or tag that triggered a run. For unmerged pull_request events, the format is the pull request number followed by /merge. That is intentionally not the same as GITHUB_HEAD_REF, which identifies the head branch in a pull request context. GITHUB_BASE_REF identifies the target branch, while GITHUB_SHA may refer to a merge commit for pull_request workflows. If a report needs to identify the actual content tested, record the event, ref, SHA and job context rather than relying on one convenient string.
Differentiate branch pushes, tags, and pull requests
Consider three synthetic runs. A branch push might provide a short name such as captions/es. A tag event might provide a release tag such as v2.3. An open pull request can provide 42/merge. These values are not interchangeable, and slash characters can alter a filesystem path if used directly. Before writing an artifact label, inspect GITHUB_EVENT_NAME and GITHUB_REF_TYPE where applicable. Avoid assuming that a name beginning with v is always a tag or that a slash always indicates a pull request. The event payload and the documented variables are the appropriate context for such decisions.
Avoid unsafe shell interpolation
Treat names influenced by repository contributors as untrusted input when constructing commands. Do not place an expression that resolves to a branch name directly into an executable shell command or an unquoted path. Pass the value through an environment variable, quote its use, and validate a restricted character set before including it in a filename. Keep branch names out of executable arguments when a fixed, opaque run identifier will do. The goal is not to hide the ref name but to prevent path traversal, unexpected shell parsing and accidental overwrites caused by punctuation in otherwise legitimate names.
Build a report key that survives reruns
A caption report needs an identifier that distinguishes one workflow execution from another. Use the run ID and run attempt, plus the checked commit SHA, as primary provenance fields. A sanitized ref label can be added for readability after those identifiers. For example, an internal report directory could contain an opaque run identifier and a JSON summary with ref_name and source_commit rather than using the raw ref as the directory name. GitHub documents that GITHUB_RUN_ATTEMPT changes on rerun, whereas GITHUB_RUN_ID remains the same. This matters when an editor compares a failed original run with a successful retry.
Record the commit that was really tested
In a pull_request workflow, GITHUB_SHA can refer to a generated merge commit, and the short ref_name can be number/merge. A test of the merge result is useful, but it is not the same as testing only the contributor’s head branch. Preserve which commit and base context the CI executed. If release approval requires proof of the exact repository tree that supplied captions, record the checked-out SHA or immutable artifact digest as applicable. A successful report filename without that provenance cannot answer whether the approved translation files were actually tested.
Compare labels with actual event data
A review worksheet can show the event type, GITHUB_REF_NAME, source head, target base, tested SHA, run ID and attempt. A pull request merge ref should be visibly different from a branch push or release tag in the illustrated examples. These are invented values for teaching, not real repository metadata. When building a release dashboard, label each field by what it means. Avoid a single ambiguous “Branch” column populated with ref_name across all event types; it will become misleading on PRs and tag releases.
Keep artifact content and access boundaries separate
Artifact naming does not make an uploaded report public or private. Protect unpublished interview captions by restricting workflow permissions, controlling artifact destinations and avoiding raw transcript text in filenames or logs. Make sure untrusted pull request code cannot run with elevated credentials merely because the ref name looks familiar. Do not use a ref_name condition as the only authorization gate for publication. Branch protection, environment approvals and least-privilege job permissions should remain independent. A benign-looking report label is not evidence that the job ran in a trusted security context.
Add a deterministic QA acceptance check
Before accepting a caption QA report, confirm that its internal metadata matches the workflow event, the checked commit and the intended language files. Validate that report paths are derived from a safe fixed prefix and opaque identifiers. On reruns, preserve both attempts rather than overwriting the earlier result. Reject reports with missing or inconsistent provenance, even if the test status is green. The objective is an auditable connection between the caption source and the test result, not a clever filename. Staff should still review caption quality and accessibility separately from the CI process.
Document the limits of a short ref name
This article describes GitHub’s documented environment variables and an illustrative museum caption workflow. We did not run a repository workflow, open private captions or measure artifact behavior. The diagrams contrast event types and naming decisions rather than depicting actual GitHub screens. Confirm the current variable definitions and event-specific SHA behavior before changing existing CI. Use ref_name for human readability only after validating its context, and use stable run and commit identifiers for machine decisions. A report that names the right branch can still describe the wrong code unless provenance is checked.
How We Research
We prepared this November 11, 2026 documentation-based guide using GitHub Docs: Variables reference; GitHub Docs: Events that trigger workflows; GitHub Docs: Workflow commands. We cross-checked the exact API field or environment variable against the official reference, then examined practical distinctions such as scope, errors, authentication, version selection and application-side review. Scenarios use fictional museum records and synthetic labels; diagrams depict concepts rather than captured interfaces or measured service results. We did not access a private API project, execute production changes, inspect protected archive objects, or run GitHub Actions. Service behavior, permission boundaries and API versions can change; consult current primary documentation and your organization’s approved policies before implementing a workflow.
Frequently Asked Questions
GitHub documents the short ref in the form <PR number>/merge, not necessarily the source branch name.
No. Branch or PR ref names can contain separators and other characters. Sanitize or avoid raw ref-derived filesystem paths.
Use the event context and GITHUB_HEAD_REF, not an assumption about GITHUB_REF_NAME.
Record GITHUB_RUN_ID together with GITHUB_RUN_ATTEMPT, plus the checked commit provenance.
No. Use proper protected environments, branch policies, reviewed approvals and least-privilege credentials.