# Debugging Failing Runs — GitHub Actions

Source: https://www.skillbyai.com/en/github-actions/p-debug

> Logs, re-runs and local tools.

## Find the cause quickly

Start with the failing step's log; expand earlier steps for context. Re-run failed jobs only, and enable **debug logging** by setting the `ACTIONS_STEP_DEBUG` secret or variable to true (or "re-run with debug logging"). Print contexts safely with `toJSON(github)` (never secrets). Upload diagnostic artifacts on failure. Reproduce locally where possible: run the same commands in a container matching the runner, or use tools such as `act` (needs Docker) for quick iterations. Check the GitHub status page when many workflows fail at once.

## Debugging helpers

Not linted or run here; check the GitHub Actions documentation for current syntax.

```yaml
- name: Dump event context (debugging only)
  env:
    EVENT: ${{ toJSON(github.event) }}
  run: echo "$EVENT" | head -50

- name: Upload logs on failure
  if: ${{ failure() }}
  uses: actions/upload-artifact@v4
  with:
    name: test-logs
    path: logs/
```

## Make CI scripts runnable locally

Put logic in scripts (make test, ./ci/build.sh) that run the same locally and in Actions, keeping workflows thin.

**Quiz:** How do you enable more detailed step logs?

- [ ] Increase the timeout
- [ ] Delete the workflow
- [x] Set ACTIONS_STEP_DEBUG to true or re-run with debug logging
- [ ] Use a macOS runner

*Answer:* Set ACTIONS_STEP_DEBUG to true or re-run with debug logging. Debug logging on demand.