Debugging and Observability

Turn up the logging

GitHub exposes debug channels that are hidden by default. Toggling ACTIONS_STEP_DEBUG and ACTIONS_RUNNER_DEBUG to true at the repository level surfaces additional logs from both your steps and the runner itself.

Use these flags (along with log grouping and artifacts) to preserve the context you need to diagnose flaky or intermittent failures.

jobs:
  # To see the debug logging in action:
  # 1. Run with no modified settings (default)
  # 2. Set ACTIONS_STEP_DEBUG repo VAR or SECRET to true
  #    └─> (This will show the debug log defined in the step)
  # 3. Set ACTIONS_RUNNER_DEBUG repo VAR or SECRET to true
  #    └─> (This will show the debug logs from the runner)
  log-at-various-levels:
    runs-on: ubuntu-24.04
    steps:
      - name: Echo some things
        run: |
          echo "::debug::This is a debug message"
          echo "::info::This is an info message"
          echo "::warning::This is an warning message"

SSH into a Failing Job

Sometimes you need to poke around the runner interactively.

Namespace's breakpoint-action can drop an SSH breakpoint when a job fails, giving you a fixed window to inspect the environment or rerun commands in place.

jobs:
  fail-with-breakpoint:
    runs-on: ubuntu-24.04
    steps:
      - name: Checkout Code
        uses: actions/checkout@ff7abcd0c3c05ccf6adc123a8cd1fd4fb30fb493 # v5.0.0
      - name: Fail
        run: |
          echo "::error Purposefully failing the job"; exit 1;
      - name: Breakpoint if Failed
        if: failure()
        uses: namespacelabs/breakpoint-action@664d004eae0e89e248fafe14fd5e97d28440a85e # v0.0.13
        with:
          duration: 10m
          authorized-users: sidpalas

Team Habits for Developer Experience

• Keep a living Taskfile, Makefile, or CLI in the repo so contributors can run the same commands locally that your workflows call in CI.
• Check in .env.example or README snippets documenting required secrets for local execution.
• Encourage teammates to capture notes when they debug with act, breakpoints, or elevated logging so the next incident is faster to resolve.

These practices help turn GitHub Actions into a productive development platform enabling you to iterate on automations quickly.