4.1.2. Diagnosing Failed Runs
💡 First Principle: Every failure in Actions ultimately surfaces as a nonzero exit code, a missing resource, or a permission denial — and the diagnostic path differs for each, so classify the failure before you start reading logs line by line.
The two debug switches are exam-critical because they're the answer to "how do you get more detail?" Setting the secret or variable ACTIONS_STEP_DEBUG to true enables ::debug:: messages and verbose step diagnostics; ACTIONS_RUNNER_DEBUG to true produces runner and worker diagnostic logs, which appear in the downloaded log archive under a runner-diagnostic-logs folder. Both are set at the repository (or org) level, not in the YAML — a distinction questions exploit. Beyond those, the Set up job section resolves the "it worked yesterday" class of failures by showing the runner image version and the exact action versions used.
Failure classes worth recognizing on sight: a 403 "Resource not accessible by integration" is GITHUB_TOKEN permissions (2.1.4) or an org-level default of read-only, never a bad PAT. An empty secret means scope, access policy, or a fork PR (3.3.1) — and note it fails downstream, at the authentication step, with a misleading message. A step that "hangs" until the 6-hour job limit is usually waiting on input (an interactive prompt, a missing -y) or a service that never became healthy (2.2.3). And a matrix showing many cancelled variants after one failure is fail-fast: true behaving normally.
Timeouts are configurable and worth knowing: jobs default to a 6-hour maximum, a whole workflow run may last up to 35 days, and timeout-minutes at the job or step level is how you fail fast instead of paying for a hung runner.
⚠️ Exam Trap: ACTIONS_STEP_DEBUG is configured as a repository secret or variable — you cannot enable it by adding a key to the workflow YAML. If an answer option shows debug: true inside the workflow file, it's wrong.
Reflection Question: A step fails with "Resource not accessible by integration" the day after someone tightened organization settings, with no change to the workflow. Name the two settings that could produce this, and the one-block fix in the workflow.
