GitHub Actions Tutorial — Debug Logging

Debug Logging

By default, GitHub Actions only shows standard output. Debug logging reveals internal runner operations, action internals, and detailed step execution — critical for diagnosing obscure failures.

---

Enable Debug Logging

Method 1 — Repository Secret

Set a repository secret:

Name:  ACTIONS_RUNNER_DEBUG
Value: true

This enables debug logging for all workflow runs until you remove the secret.

Method 2 — Re-run with Debug

In the GitHub UI: failed workflow run → Re-run jobs → check “Enable debug logging” → Re-run.

This enables debug logging for a single re-run — no secret needed.

---

What Debug Logging Shows

Level	Content
Standard	Step output, error messages
Debug	Runner internals, action debug messages, environment setup

Standard Output

Run npm test
> my-app@1.0.0 test
> jest
PASS  tests/app.test.js

Debug Output

##[debug]Evaluating condition for step: 'Run npm test'
##[debug]Evaluating: success()
##[debug]Result: true
##[debug]Starting: Run npm test
##[debug]Loading inputs
##[debug]Resolved path: /home/runner/work/my-app/my-app

---

Step Debug Logging

Enable step-level debug output with another secret:

Name:  ACTIONS_STEP_DEBUG
Value: true

This reveals:

• Condition evaluation for if: expressions
• Input/output resolution for each step
• File matching patterns (for caching, artifacts)
• Timing details for each operation

---

Writing Debug Messages in Your Workflows

steps:
  - name: Debug info
    run: |
      echo "::debug::Current directory: $(pwd)"
      echo "::debug::Node version: $(node --version)"
      echo "::debug::Files in workspace:"
      ls -la

Debug messages with ::debug:: only appear when debug logging is enabled.

In JavaScript Actions

const core = require('@actions/core');

core.debug('Processing started');
core.debug(`Input value: ${core.getInput('name')}`);
core.info('This always shows');
core.warning('This shows as a warning annotation');

---

Common Mistakes

Mistake	Fix
Debug logging too verbose	Use Method 2 (re-run) for one-off debugging instead of the secret
Forgot to remove ACTIONS_RUNNER_DEBUG	Delete the secret after debugging
Sensitive data in debug output	Debug logs can expose env vars — review before sharing
Can’t find the issue	Combine with ACTIONS_STEP_DEBUG for maximum detail

---

Quick Reference

Setting	Secret Name	Scope
Runner debug	ACTIONS_RUNNER_DEBUG=true	All runs
Step debug	ACTIONS_STEP_DEBUG=true	All runs
One-time debug	Re-run with debug checkbox	Single run
In-workflow	echo "::debug::message"	When debug enabled

---

← Back to: Chapter 14: Troubleshooting

Next: Common Errors →