Enabling Step Debug Logging
The failed run from the earlier debugging chapter only gave up its secret once we added a step to cat the app’s own log. The GitHub Actions log itself stayed quiet the whole way through otherwise. There’s a much chattier mode hiding behind two flags, and this chapter turns it on.
The Two Debug Flags
ACTIONS_STEP_DEBUG— increases the verbosity of every step’s own log during and after execution, surfacing extra detail from the actions you use (resolved inputs, internal decisions).ACTIONS_RUNNER_DEBUG— adds two extra log files to the run’s downloadable log archive: one covering the runner’s coordination with GitHub, one covering the worker process that actually executes your steps.
Both are enabled by setting a repository secret or variable with that exact name, value true. A secret takes precedence over a variable of the same name.
Note
These aren’t env: keys in your YAML — they’re repository-level secrets or variables GitHub Actions checks for automatically. Setting them is enough; you don’t reference them anywhere in the workflow file.
Turning Them On
Settings → Secrets and variables → Actions, add ACTIONS_STEP_DEBUG and ACTIONS_RUNNER_DEBUG (as secrets or variables — either works, since neither name holds sensitive data), both set to true.
Tip
Anyone with permission to run a workflow can also force both kinds of debug logging on for a single re-run, without touching repository secrets at all — covered next. Setting the secrets is the “leave it on for a while” option; the re-run flag is the “just this once” option.
Re-running With Debug Logging On
From the GitHub UI: open the failed run from the earlier debugging chapter, click the dropdown next to Re-run jobs, and pick Re-run jobs with debug logging.
From the gh CLI:
gh run rerun <run-id> --debugFind the run ID first if you need it:
gh run list --workflow=deploy-app-debug.yml --limit 5What Changes In The Log
Re-run the same broken pipeline — still pointed at the renamed APP_PORT bug — with debug logging on. The outcome is identical: it still fails, for the same reason. What changes is the texture of the logs along the way.
With ACTIONS_STEP_DEBUG on, steps built from actions (like actions/checkout or actions/setup-python, if your version of this pipeline uses one) interleave their normal output with lines prefixed ##[debug], showing resolved inputs and internal decisions that are invisible in the plain log. Steps built from plain run: blocks — most of this pipeline — show comparatively little extra, since there’s no action internals to expose; you mostly get the runner’s own step-timing and environment-setup detail.
With ACTIONS_RUNNER_DEBUG on, the run’s log archive (download it from the run page’s gear icon) gains a runner-diagnostic-logs folder with two extra files: the runner’s coordination log and the worker’s execution log. Reach for these when a job fails to start at all, hangs before your first step logs anything, or behaves differently than a nearly-identical run — situations where the problem is in how the job got run, not in what your steps did.
For this particular bug, neither flag changes the diagnosis — the root cause is inside the app process itself, which is exactly why the earlier debugging chapter’s if: failure() step that cats app.log was the thing that actually found it. Debug logging makes your pipeline’s own behavior more transparent, but it can’t see inside a program your pipeline merely launched.
Tip
Step debug logging can reveal resolved values and internal state that are normally hidden. Avoid leaving ACTIONS_STEP_DEBUG on permanently for a repository with anything sensitive in it — turn it on when you’re actively troubleshooting, and off again after.
Cleaning Up
If you set the two secrets just for this exercise, remove them from Settings → Secrets and variables → Actions. Keep deploy-app-debug.yml and the debug-exercise branch around a little longer — the next chapter reuses this same failure as the running example for a broader catalog of failure patterns.