How to debug GitHub Actions failures?

· Category: DevOps & CI/CD

Short answer

Debug GitHub Actions by examining job logs, reproducing locally, enabling step debugging, and using the workflow commands to inspect the environment.

Steps

  1. Read the job logs for error messages.
  2. Reproduce the failure locally or with act.
  3. Enable debug logging by setting ACTIONS_STEP_DEBUG.
  4. Add debug steps to print environment variables.

Example

steps:
  - run: env
  - run: cat $GITHUB_EVENT_PATH
  - run: ls -la

Tips

  • Use jobs.<job_id>.if to skip unaffected jobs during debugging.
  • Use workflow_dispatch inputs to control behavior.
  • Use tmate action for interactive debugging on the runner.

Common issues

  • Environment differences between runners and local machines cause failures.
  • Secrets are not available in pull requests from forks.
  • YAML syntax errors prevent workflows from starting.
  • Outdated actions cause deprecation warnings or failures.