GitHub Actions ACTIONS_RUNNER_DEBUG: Diagnose Caption CI Without Publishing Private Runner Logs

An intermittent runner failure needs bounded evidence

Imagine a museum website build that tests caption timing before an accessibility release. Most jobs pass, but some stop during environment setup before the caption linter executes. Engineers may need runner-level diagnostics, yet turning on verbose logging for every run could expose more operational detail than the editorial team should see. GitHub Actions supports ACTIONS_RUNNER_DEBUG for runner diagnostic logging. This is a troubleshooting switch, not a way to improve code correctness or to certify caption quality. Decide which run requires diagnosis, who can access its logs and when diagnostics should be disabled before collecting anything.

Use the documented switch name and value

GitHub instructs repository administrators to set a secret or variable named ACTIONS_RUNNER_DEBUG to true to enable runner diagnostic logging. If both a secret and variable use that name, the secret takes precedence. Check whether the value is configured at the appropriate repository, organization or environment scope for the targeted workflow. Do not silently add a permanent debugging setting to every repository in an organization. Record who approved the change and what failed. A variable controlling verbosity is not an authentication mechanism, and the presence of the value does not prove that any particular job will run successfully.

Distinguish runner diagnostics from step debugging

ACTIONS_RUNNER_DEBUG concerns runner process and worker process diagnostic logs. ACTIONS_STEP_DEBUG is a different control that increases step-log verbosity. The runner.debug context can support conditional behavior when debug logging is enabled, but it should not be used as a proxy for reviewer authorization. Choose the smallest signal that answers the incident question: step output may help a faulty command, while runner diagnostics may help execution setup or runner coordination. Activating both without a reason can multiply the sensitive details copied into downloadable archives. The comparison illustration separates three states instead of showing all logging as one generic “debug” mode.

Know where the additional files appear

According to GitHub’s documentation, runner diagnostic logging adds runner process and worker process logs to the downloadable workflow-run log archive under runner-diagnostic-logs. The files are not automatically an approved public artifact and should not be posted to a museum issue tracker without review. Restrict archive access to the relevant engineering operators. Keep identifying data about the CI environment out of public screenshots. If a team needs to explain a failure to curators, summarize the specific diagnostic finding and provide a redacted, permitted excerpt rather than handing over raw infrastructure logs.

Protect secrets and sensitive caption sources

A caption test may process unpublished interviews, donor names or embargoed exhibition materials. Enable diagnostic collection only after reviewing whether commands, paths or error handlers might output portions of those sources. GitHub masks many configured secret values, but masking is not a complete privacy boundary for transformed tokens, arbitrary personal data or command-line arguments. Avoid echoing credentials and data to logs at any verbosity. Review what the workflow prints, where test fixtures live and who has permission to download log archives. A clean-looking debug log does not prove that all secrets were protected.

Reproduce one failure without rerunning a release blindly

For a hypothetical intermittent setup problem, start by recording the workflow run ID, job name, attempt and affected runner environment. Check ordinary logs first. If the cause remains unclear, enable runner diagnostics for a controlled rerun only when rerunning cannot repeat an unsafe deployment or notification. A rerun may execute side effects and is not inherently harmless. Capture the log archive, identify the minimal relevant lines and compare them with a known-good run only when both are permitted. Use the current job status and downstream publishing ledger rather than treating a diagnostic rerun as approval to release an exhibit.

Compare normal, runner and step logging

A normal run can provide enough evidence for a missing dependency or syntax error. Runner diagnostics add information about coordination and worker operation, while step debugging adds more detailed output from job steps. Each extra layer should have a reason and an audience. A three-column diagram can show that these modes create different classes of information and different review obligations. It must not show fictitious real-time timings or claim a certain number of bytes collected. Decide whether the question is about runner setup, an individual action or the caption validation result before choosing a debug switch.

Write a short-lived change and access policy

Log collection should have an incident ID, approving owner, intended run scope, access list and removal checkpoint. Treat an organization-wide secret or variable as potentially affecting more workflows than a narrowly scoped repository setting. After the diagnostic case closes, return debug settings to the approved baseline and document that the review occurred. Follow your organization’s retention rules for copied archives, especially when logs contain unpublished captions. Do not treat a repository variable as a reliable way to conceal a secret; permission boundaries, secure commands and minimal outputs remain essential.

Verify the fix with ordinary runs afterward

A runner diagnostic archive may suggest a permission, dependency or network issue. Resolve it through a reviewed code or configuration change, then validate with the normal logging level. Confirm that the caption QA actually ran against the intended source commit and that publication gates still require their original approvals. Do not archive a green workflow badge as sole proof of accessibility quality; inspect the specific report and the edition of the caption files checked. If the failure returns, preserve a trace of the new run rather than assuming the first diagnosis covered every environment.

Keep this a documented troubleshooting procedure

The steps here are derived from GitHub’s published debugging and secrets guidance. We did not access a private repository, turn on debug variables, inspect actual caption files or download a workflow log archive. The drawings depict conceptual runner and log flows, not captures of a real GitHub interface. Before using this procedure, confirm your plan’s permissions, the current location of log archives and any repository or organization restrictions. Review new logs for sensitive data before distributing an excerpt, and disable enhanced diagnostics when the specific incident no longer requires them.

Related guides

• GitHub Actions RUNNER_ARCH: Select a Caption Checker Binary for the Actual CPU
• GitHub Actions RUNNER_TOOL_CACHE: Find Caption Validators Without Assuming They Are Trusted
• GitHub Actions RUNNER_NAME: Trace Caption Checks Without Treating a Runner Label as Unique

How We Research

For this November 11, 2026 documentation-based review, we consulted GitHub Docs: Enabling debug logging; GitHub Docs: Using secrets in GitHub Actions. We checked the named API fields, scope, failure paths and relevant limitations against a hypothetical museum workflow, and compared operations with nearby endpoints when that distinction affected safe use. We did not access any private account, issue destructive API calls, run a CI job, inspect actual source content or make benchmark measurements. The artwork consists of original schematic illustrations rather than captured vendor interfaces. Before applying an operational change, confirm the latest official documentation, verify the target account and resource identifiers, and obtain the required organizational approvals.

Frequently Asked Questions