Document RUNNER_DEBUG#55
Conversation
📝 WalkthroughWalkthroughTwo README files updated: the first “FlakeHub Cache” mention is converted to a named link, two headings had trailing exclamation marks removed, a new “Debugging mode” section documents RUNNER_DEBUG/ACTIONS_* debug vars and shows a workflow snippet, and the link-reference block was consolidated and adjusted. ChangesDocumentation updates (single cohort)
Estimated Code Review Effort🎯 2 (Simple) | ⏱️ ~8 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Review rate limit: 4/5 reviews remaining, refill in 12 minutes. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@tools/README.template.md`:
- Around line 128-130: Fix the malformed flakehub link reference by updating the
URL string "https//flakehub.com" referenced by [flakehub] to include the missing
colon, i.e., change it to "https://flakehub.com" so the [flakehub] reference
resolves to a valid URL in the generated docs.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 11bf40ed-34a9-4ca2-822a-9d7f9921bc39
📒 Files selected for processing (2)
README.mdtools/README.template.md
There was a problem hiding this comment.
🧹 Nitpick comments (1)
tools/README.template.md (1)
128-130: 💤 Low valueConsider removing unused link reference definitions.
The
[flakehub]URL is now correctly formatted (fixing the previous review's concern). However, static analysis indicates that[detsys]and[flakehub]reference definitions are not used anywhere in the document.If these are intentionally reserved for future use in the template, this can be ignored. Otherwise, removing unused references improves maintainability.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@tools/README.template.md` around lines 128 - 130, The README.template contains link reference definitions [detsys], [flakehub], and [gha-env-vars]; static analysis shows [detsys] and [flakehub] are unused. Remove the unused reference definition lines for [detsys] and [flakehub] from the bottom of the file (leave [gha-env-vars] if it is used), or if they are intentionally reserved, add a short inline comment near the definitions clarifying their purpose; update references in the template to use these identifiers if they should remain in active use.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@tools/README.template.md`:
- Around line 128-130: The README.template contains link reference definitions
[detsys], [flakehub], and [gha-env-vars]; static analysis shows [detsys] and
[flakehub] are unused. Remove the unused reference definition lines for [detsys]
and [flakehub] from the bottom of the file (leave [gha-env-vars] if it is used),
or if they are intentionally reserved, add a short inline comment near the
definitions clarifying their purpose; update references in the template to use
these identifiers if they should remain in active use.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: f8ef025b-3985-4e3b-9c3e-3a3a2ebd6dd9
📒 Files selected for processing (2)
README.mdtools/README.template.md
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@tools/README.template.md`:
- Around line 100-108: Replace the incorrect workflow example that sets
RUNNER_DEBUG in step env with guidance that debug logging cannot be enabled from
a workflow step; update the text to mention the correct variables
ACTIONS_STEP_DEBUG=true and ACTIONS_RUNNER_DEBUG=true and instruct users to set
those at the repository/organization level (or as secrets/variables) instead of
in-step env, and either remove the example YAML block or replace it with a link
to the GitHub Actions debug logging docs
(https://docs.github.com/en/actions/managing-workflow-runs/enabling-debug-logging)
for how to enable debug logging.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 0cc5b785-87ad-415b-adfc-6ca49f895c70
📒 Files selected for processing (2)
README.mdtools/README.template.md
| If you're having issues pushing to FlakeHub Cache and would like deeper insight into potential causes, we recommend [enabling verbose logging][gha-env-vars] by setting the `RUNNER_DEBUG` environment variable to `1`. | ||
| Here's an example: | ||
|
|
||
| ```yaml | ||
| steps: | ||
| - name: Push to FlakeHub Cache | ||
| env: | ||
| RUNNER_DEBUG: 1 | ||
| uses: DeterminateSystems/flakehub-cache-action@<!-- version_major --> |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
cat -n tools/README.template.md | sed -n '95,115p'Repository: DeterminateSystems/flakehub-cache-action
Length of output: 999
🌐 Web query:
GitHub Actions enable debug logging ACTIONS_STEP_DEBUG RUNNER_DEBUG
💡 Result:
To enable GitHub Actions debug logging, set these repository-level secrets or variables to true (the secret value takes precedence over the variable): 1) Step debug logging - Set ACTIONS_STEP_DEBUG = true. - Result: more verbose step log events. 2) Runner (diagnostic) debug logging - Set ACTIONS_RUNNER_DEBUG = true. - Result: additional runner diagnostic logs are added to the workflow run log archive under the runner-diagnostic-logs folder. How to check from within an action - Use ${{ runner.debug }} / runner.debug context to conditionally run steps when debug logging is enabled. - The @actions/core utility’s core.isDebug maps to this (via the RUNNER_DEBUG environment variable) so your action can increase verbosity when debug is on. Example workflow usage - if: runner.debug == '1' to gate extra logging. Note: these debug settings are enabled via repository secrets/variables for the workflow’s repository (not by setting them inside the workflow file’s env).
Citations:
- 1: https://docs.github.com/en/actions/managing-workflow-runs/enabling-debug-logging
- 2: https://docs.github.com/actions/managing-workflow-runs/enabling-debug-logging
- 3: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands
- 4: https://stackoverflow.com/questions/75434105/how-to-determine-if-the-github-action-is-running-with-debug-logging-enabled
- 5: Expose whether debug is on/off via RUNNER_DEBUG. actions/runner#253
RUNNER_DEBUG cannot be enabled via step env; docs should point to ACTIONS_STEP_DEBUG or ACTIONS_RUNNER_DEBUG instead.
The current example tells users to set RUNNER_DEBUG: 1 in a step's env section, but GitHub Actions debug logging must be enabled via repository-level secrets or variables, not in the workflow file. The correct variables are ACTIONS_STEP_DEBUG=true (for step-level logs) or ACTIONS_RUNNER_DEBUG=true (for runner diagnostic logs). Setting them in the workflow as shown would not enable debug logging as described.
Either remove the workflow example entirely and explain that debug logging must be configured at the repository level, or update the reference link to point to the GitHub Actions debug logging documentation.
🧰 Tools
🪛 LanguageTool
[style] ~100-~100: Consider a different adjective to strengthen your wording.
Context: ...ushing to FlakeHub Cache and would like deeper insight into potential causes, we recom...
(DEEP_PROFOUND)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@tools/README.template.md` around lines 100 - 108, Replace the incorrect
workflow example that sets RUNNER_DEBUG in step env with guidance that debug
logging cannot be enabled from a workflow step; update the text to mention the
correct variables ACTIONS_STEP_DEBUG=true and ACTIONS_RUNNER_DEBUG=true and
instruct users to set those at the repository/organization level (or as
secrets/variables) instead of in-step env, and either remove the example YAML
block or replace it with a link to the GitHub Actions debug logging docs
(https://docs.github.com/en/actions/managing-workflow-runs/enabling-debug-logging)
for how to enable debug logging.
There was a problem hiding this comment.
Could you double check this? I think you can set it in the YAML config as well.
There was a problem hiding this comment.
@lucperkins, I've double-checked and my original concern holds up. Here's the nuance:
Setting RUNNER_DEBUG in a step's env: does not actually enable GitHub Actions' built-in debug logging. Here's why:
-
RUNNER_*are reserved default environment variables that GitHub explicitly states cannot be overwritten viaGITHUB_ENV. While writingRUNNER_DEBUG: 1in a step'senv:block does technically inject it into that step's process environment, it does not trigger GitHub's debug logging subsystem — the runner reads the debug flag before any step env is applied. -
To activate GitHub Actions debug logging, the correct approach is to add
ACTIONS_RUNNER_DEBUG = true(for runner diagnostic logging) orACTIONS_STEP_DEBUG = true(for step debug logging) as repository secrets or variables. -
These two repository secrets control the behavior:
ACTIONS_STEP_DEBUGfor verbose output for each step, andACTIONS_RUNNER_DEBUGfor runner-level diagnostic information. You can also trigger debug mode without modifying secrets by selecting "Re-run jobs" and checking the "Enable debug logging" option when re-running a failed workflow.
The current file content in the PR (the expanded version) already documents all three variables and mentions they can be set in the workflow YAML or as repo secrets. However, the statement that RUNNER_DEBUG can be set in a workflow YAML step env to produce the ZIP log archive behaviour described in the docs is still inaccurate — that archive is specifically generated when ACTIONS_RUNNER_DEBUG=true is set as a repository secret/variable.
The most accurate guidance would be:
- Use
ACTIONS_STEP_DEBUG=trueorACTIONS_RUNNER_DEBUG=trueas repository secrets or variables (not in-stepenv:) to enable the native GitHub debug logging and ZIP archive download. - The
RUNNER_DEBUGvariable in a stepenv:may be read by the action's own code (like@actions/core'sisDebug()), but it won't enable GitHub's debug log archive feature.
There was a problem hiding this comment.
Could you show me where this is documented?
There was a problem hiding this comment.
🧩 Analysis chain
@lucperkins, here are the official GitHub docs and community discussions that support the concern:
-
GitHub's official Variables reference explicitly states: "You can't overwrite the value of the default environment variables named
GITHUB_*andRUNNER_*." This is also repeated verbatim in the Workflow commands for GitHub Actions page. SinceRUNNER_DEBUGis aRUNNER_*variable, it falls under this restriction. -
A GitHub Community discussion (
#52079) confirms this empirically: "Setting theRUNNER_DEBUGenvironment variable in a step doesn't [make]runner.debugreturn'1'."
So while setting RUNNER_DEBUG: 1 in a step's env: block may inject the value into the process environment for that step, it does not trigger GitHub Actions' built-in debug logging subsystem — the runner reads the debug flag before any step env is applied, and RUNNER_* variables are protected from being overwritten.
The correct approach to enable GitHub Actions debug logging (including the ZIP log archive) is to set ACTIONS_STEP_DEBUG=true or ACTIONS_RUNNER_DEBUG=true as repository secrets or variables — not in the workflow YAML's env: block.
🌐 Web query:
GitHub Actions RUNNER_DEBUG reserved environment variable cannot overwrite
💡 Result:
RUNNER_DEBUG is a default GitHub Actions runner environment variable (RUNNER_*) and cannot be set/overwritten via env: (job/step/workflow) or by writing to $GITHUB_ENV. GitHub blocks overwriting any RUNNER_* (and GITHUB_*) variables; RUNNER_DEBUG is only present when debug logging is enabled and, when set, it has the value 1. [1]
What to do instead (to enable it):
- Enable runner diagnostic logging by setting the repository/org secret or variable:
ACTIONS_RUNNER_DEBUG=true
GitHub will then automatically setRUNNER_DEBUG=1during the run. [2]
(Optional) For step debug logs:
ACTIONS_STEP_DEBUG=true[2]
Example usage in a workflow (don’t set RUNNER_DEBUG; just read it):
- name: Only run in runner debug mode
if: ${{ runner.debug == '1' }}
run: echo "Runner debug is enabled (RUNNER_DEBUG=$RUNNER_DEBUG)"Sources
- [1] GitHub Docs — Default variables cannot be overwritten;
RUNNER_DEBUGbehavior: (docs.github.com) - [2] GitHub Docs — Enabling debug logging via
ACTIONS_RUNNER_DEBUG/ACTIONS_STEP_DEBUG: (docs.github.com)
Citations:
- 1: https://docs.github.com/en/actions/reference/workflows-and-actions/variables?utm_source=openai
- 2: https://docs.github.com/actions/managing-workflow-runs/enabling-debug-logging?utm_source=openai
@lucperkins, here's what the official GitHub documentation says:
RUNNER_DEBUG is a default GitHub Actions runner environment variable (RUNNER_*) and cannot be set or overwritten via env: (job/step/workflow) or by writing to $GITHUB_ENV.
GitHub blocks overwriting any RUNNER_* (and GITHUB_*) variables. RUNNER_DEBUG is only present when debug logging is enabled by GitHub itself, and when set, it has the value 1.
The correct way to enable it, per the docs:
- Enable runner diagnostic logging by setting the repository/org secret or variable
ACTIONS_RUNNER_DEBUG=true— GitHub will then automatically setRUNNER_DEBUG=1during the run. - For step debug logs, use
ACTIONS_STEP_DEBUG=true.
So the workflow example in the PR (env: RUNNER_DEBUG: 1) would be silently ignored by the runner's debug subsystem. The documentation would be more accurate if it directed users to set ACTIONS_RUNNER_DEBUG or ACTIONS_STEP_DEBUG as repository secrets/variables, or mentioned the Re-run with debug logging UI option in GitHub Actions.
There was a problem hiding this comment.
♻️ Duplicate comments (1)
tools/README.template.md (1)
100-108:⚠️ Potential issue | 🟠 Major | ⚡ Quick winDebugging instructions currently conflate debug toggles and runtime debug context.
This section links to default env vars docs and implies
RUNNER_DEBUGcan be used the same way asACTIONS_STEP_DEBUG/ACTIONS_RUNNER_DEBUGto enable debug logging. GitHub’s debug-logging docs describe enabling viaACTIONS_STEP_DEBUG/ACTIONS_RUNNER_DEBUG(repo/org variable or secret), whileRUNNER_DEBUGis primarily exposed at runtime when debug mode is already on. Please update the wording + link so users don’t follow a non-working troubleshooting path.Proposed doc fix
-If you're having issues pushing to FlakeHub Cache and would like deeper insight into potential causes, we recommend enabling verbose logging by setting one of these [environment variables][gha-env-vars] to either `1` or `true`: +If you're having issues pushing to FlakeHub Cache and would like deeper insight into potential causes, enable GitHub Actions debug logging as documented [here][gha-debug-logging]: -- `RUNNER_DEBUG` - `ACTIONS_STEP_DEBUG` - `ACTIONS_RUNNER_DEBUG` -When you set one of these, GitHub Actions generates a ZIP archive of the runner's logs that you can download by clicking **Download log archive** in the dropdown menu for that run. -You can set these variables either in your workflow YAML configuration in `.github/workflows` or as a repository-wide secret or environment variable. +Set one of the variables above to `true` (or `1`) as a repository/organization variable or secret. +When debug logging is enabled, you can download the run logs from the Actions UI (**Download log archive**). + +`RUNNER_DEBUG` is available inside a run when debug logging is active, so actions can detect debug mode.-[gha-env-vars]: https://docs.github.com/en/actions/reference/workflows-and-actions/variables#default-environment-variables +[gha-debug-logging]: https://docs.github.com/actions/managing-workflow-runs/enabling-debug-loggingGitHub Actions docs: Is RUNNER_DEBUG an input toggle or a runtime environment indicator, and what are the officially supported variables to enable debug logging?Also applies to: 132-132
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@tools/README.template.md` around lines 100 - 108, The paragraph incorrectly groups RUNNER_DEBUG with ACTIONS_STEP_DEBUG and ACTIONS_RUNNER_DEBUG as equivalent toggles; update the text so it clearly states that ACTIONS_STEP_DEBUG and ACTIONS_RUNNER_DEBUG are the supported toggles to enable debug logging (can be set as repo/org secrets or environment variables) and that RUNNER_DEBUG is a runtime indicator exposed by the runner when debug mode is already active (not a user-facing toggle), remove RUNNER_DEBUG from the actionable list, update the wording and link to the official GitHub Actions debug-logging documentation, and make the same wording correction in the other occurrence that references these environment variables.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Duplicate comments:
In `@tools/README.template.md`:
- Around line 100-108: The paragraph incorrectly groups RUNNER_DEBUG with
ACTIONS_STEP_DEBUG and ACTIONS_RUNNER_DEBUG as equivalent toggles; update the
text so it clearly states that ACTIONS_STEP_DEBUG and ACTIONS_RUNNER_DEBUG are
the supported toggles to enable debug logging (can be set as repo/org secrets or
environment variables) and that RUNNER_DEBUG is a runtime indicator exposed by
the runner when debug mode is already active (not a user-facing toggle), remove
RUNNER_DEBUG from the actionable list, update the wording and link to the
official GitHub Actions debug-logging documentation, and make the same wording
correction in the other occurrence that references these environment variables.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 1fefa306-9024-4613-b257-f26ccc1bf6dd
📒 Files selected for processing (2)
README.mdtools/README.template.md
2 participants
Summary by CodeRabbit