Enable step debug logging in a workflow

Debug logging in GitHub Actions exposes low-level details about workflow execution, making it easier to diagnose issues in jobs and steps. This guide covers:

• What debug logging is and when to use it
• How to enable it via secrets or variables
• A demo workflow showing debug logging in action
• Managing debug settings by default at the repository level

What Is Debug Logging?

By default, GitHub Actions logs include only high-level execution output. When you need deeper insights—such as condition evaluations, environment variable settings, and runner internals—you can turn on debug logging.

Types of Debug Logging

Use one or both of the following:

Enabling Debug Logging via Secrets or Variables

To activate debug logging for a run, add one or both keys as repository secrets or repository variables:

# Enable runner diagnostic logging
ACTIONS_RUNNER_DEBUG = true

# Enable step debug logging
ACTIONS_STEP_DEBUG  = true

If both secret and variable exist for the same key, the secret value overrides the variable.

Demo: Creating and Observing a Debug Workflow

This demo shows a simple workflow that fails intentionally, illustrating how step debug logging provides extra detail.

1. Create a New Repository

1. In GitHub, create a public repo named debug-workflow-demo with a README.md.
2. Clone the repository locally or open it in VS Code.

2. Add the Workflow File

Create file .github/workflows/debug.yaml with the following content:

name: Debugging Demo

on:
  workflow_dispatch:

env:
  USER_1: "foo-user"
  USER_2: "bar-user"

jobs:
  debug_job:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4

      - name: Set USERNAME from USER_1
        run: |
          echo "USERNAME=$USER_1" >> $GITHUB_ENV

      - name: Print USERNAME and Fail
        run: |
          echo "Printing USERNAME from previous step"
          echo "Username: $USERNAME"
          exit 1

      - name: Print USER_2
        run: |
          echo "Printing USER_2: $USER_2"

Commit and push:

git add .github/workflows/debug.yaml
git commit -m "Add debug workflow"
git push

3. Run Without Debug Logging

1. In the repo, go to Actions → Debugging Demo.
2. Click Run workflow.

The third step fails and the fourth step is skipped:

Default logs only display commands and outputs, without showing condition evaluations or skipped steps details.

Enabling Step Debug Logging in the UI

1. On the failed run’s page, click Re-run jobs ▶︎ Re-run with debug logging.
2. The job reruns and prepends each log line with ##[debug]:

Sample condition evaluation output:

##[debug]Evaluating condition for step: 'Checkout Repository'
##[debug]Evaluating: success()
##[debug]=> true
##[debug]Result: true
##[debug]Starting: Checkout Repository

And insight into skipped steps:

##[debug]Evaluating condition for step: 'Print USER_2'
##[debug]=> false
##[debug]Skipping step 'Print USER_2'

Downloading Runner Diagnostic Logs

After rerunning with debug, you can Download log archive from the run’s summary. The ZIP includes:

• All job logs with ##[debug] entries
• A runner-diagnostic-logs folder containing runner internals

Enabling Debug Logging by Default

To apply debug settings to every workflow run:

1. Navigate to Settings → Secrets and variables → Actions → Variables.

2. Click New repository variable and add:

   • ACTIONS_RUNNER_DEBUG = true
   • ACTIONS_STEP_DEBUG = true

Precedence: Variables vs. Secrets

If a key exists as both a variable and a secret, the secret value takes precedence:

By following these steps, you can enable and customize both step-level and runner-level debug logging in GitHub Actions, giving you full visibility into your workflow executions.