A caption checker fails on a new runner
A museum website has a GitHub Actions workflow that checks subtitle files before publication. One job uses an absolute directory written for an old runner layout; after moving to a different runner, the checker silently scans the wrong folder and reports zero violations. GitHub provides GITHUB_WORKSPACE as the default working directory for steps and the usual location of repository contents after checkout. Using it helps make a workflow portable, but it does not guarantee that files were checked out or that a path is safe. This is a fictional CI failure pattern; the diagrams show concepts rather than an actual repository or recorded test.
Read the documented meaning of the variable
GitHub’s variables reference describes GITHUB_WORKSPACE as the default working directory on the runner for steps and the default location of a repository when using a checkout action. A typical GitHub-hosted Linux path includes runner work directories followed by the repository name, but it should not be hard-coded. The workspace differs from GITHUB_ACTION_PATH, which identifies the directory of a composite action, and from RUNNER_TEMP, which is temporary runner storage. Do not assume all runners use Linux paths or the same capitalization. In a shell step, read the existing GITHUB_WORKSPACE environment variable rather than attempting to overwrite a GitHub-provided default.
Confirm checkout before reading input files
A workflow can start with an empty working directory. The actions/checkout step populates the workspace or a configured subdirectory, subject to its options. Verify the checkout version, ref, sparse-checkout settings, and any custom path before deciding where the caption files live. If the workflow deliberately checks out multiple repositories, specify exactly which one contains the captions. Do not use a green job summary as evidence that the files were present; add an explicit check that the expected caption directory and a reasonable file set exist. A missing file should fail or clearly mark the audit incomplete, not count as a clean accessibility result.
Construct paths as data
Pass the workspace root through a normal environment variable or read it in a script, then build paths with the operating system’s path utilities. For example, Python’s pathlib can join a trusted root with a reviewed relative captions path. Quote shell expansions to avoid splitting paths with spaces. Never concatenate untrusted pull-request filenames directly into shell program text or use eval. Even when GITHUB_WORKSPACE itself is provided by GitHub, individual filenames and subdirectories may come from untrusted commits. Treat these names as data; normalize paths and reject attempts to escape the approved repository subtree before opening or writing files.
Understand workspace versus temporary files
Generated caption QA logs, intermediate transcripts, and test outputs should not be mixed casually with source captions. Some reports may belong in a dedicated output directory under the workspace for artifact upload; highly sensitive temporary files may require a different restricted location and safe cleanup. RUNNER_TEMP is not the same as a durable audit archive. Decide which files an artifact upload pattern includes and confirm it does not accidentally capture .env files, internal notes, or unpublished interview transcripts. GitHub actions/upload-artifact behavior and hidden-file rules can change; review the installed action version and explicit include paths instead of assuming the entire workspace is a safe artifact.
Distinguish the repository from a third-party action
GITHUB_WORKSPACE is about the job’s checkout workspace, not the code directory of every action being invoked. A composite action that stores its own helper script should locate it using the action-specific path mechanism where appropriate, while a repository caption checker should read the checkout root. Confusing these roots can either fail to find the script or execute a file supplied by a contributor. Avoid putting helper binaries into locations that an untrusted pull request can replace when the job has privileges. Pin reviewed action versions or commit SHAs according to organizational policy and keep workflow token permissions minimal.
Protect against path traversal and symlinks
A captions directory may contain names with spaces, Unicode characters, or unexpected relative components. Do not reject legitimate filenames merely because they are unusual, but ensure resolved paths remain under the approved checkout root. Consider symlinks: a path that looks internal lexically can point outside the workspace after resolution. Validate the intended behavior for links and fail on any access that would expose secrets or unrelated files. Avoid extracting untrusted archives straight into the workspace without checks. These steps reduce mistakes; they do not turn an untrusted pull-request job into a trusted release environment.
Compare failure states without fabricated results
A useful before-and-after diagram shows a hard-coded Linux directory missing caption inputs, a workspace-relative path locating a checked-out captions folder, and an additional guard rejecting an unsafe path. These states illustrate design choices; no real runner was benchmarked or compromised for this article. If your team evaluates the workflow, test on an approved pull request with synthetic subtitle files, deliberate missing-folder cases, filenames with spaces, and an attempted path escape. Record the observed files scanned and checks executed, not merely a single pass/fail badge. Ensure skipped jobs cannot masquerade as completed accessibility review.
Final gate for a caption pull request
Before the caption change is eligible for publication, confirm the tested commit and checkout, the actual workspace root, the list of caption files scanned, any skipped checks, and the completed accessibility report. Separately require editorial review of reading order, timing, and rights for real captions. An environment variable is a helpful path hint, not a security sandbox, review approval, or guarantee of complete coverage. Keep secrets and personal interview content out of public CI artifacts. Recheck the GitHub documentation and action versions when runner images, checkout options, or workflow triggers change; this article makes no claim to have tested a production workflow.
How We Research
We reviewed GitHub Actions variables reference and GitHub actions/checkout documentation and GitHub Actions security hardening, focusing on the exact API parameter, its documented scope, required configuration, and limitations. We drafted a hypothetical museum workflow from those references and illustrated it with original conceptual diagrams. We did not query a live customer environment, conduct API benchmarks, perform security tests, inspect visitor data, or verify any real grant, rights clearance, or release approval. Any numerical or before-and-after states in diagrams are explanatory, not measured outcomes. Availability, API versions, permissions, and costs may change; check the current provider documentation and your own organization’s policies before deployment.
Frequently Asked Questions
No. A checkout step or equivalent operation must place the repository files in the workspace.
No. GITHUB_WORKSPACE is the job workspace; GITHUB_ACTION_PATH refers to a composite action’s own location.
Yes. Untrusted filenames, symlinks, and path traversal can access unintended resources unless validated.
No. Upload explicit reviewed paths and exclude private files, secrets, and unpublished transcript content.
No. Verify the checkout ref, commit, path, and file coverage independently from the environment variable.