Debugging Workflows

The debug toolkit

Re-run with debug logging — UI button on a failed run; or set ACTIONS_RUNNER_DEBUG=true + ACTIONS_STEP_DEBUG=true as repo secrets. Logs become 5–10× longer, but you see every API call.
Step debug action — mxschmitt/action-tmate opens an SSH session to the runner mid-job. Useful (and dangerous — anyone watching the session steals secrets).
Step Summary — append diagnostic info to $GITHUB_STEP_SUMMARY from inside the failing step.
Artifact dumps — if: always() upload the failure-relevant files (logs, screenshots, env dumps) so you can download and inspect.
Reproduce locally — same image, same env, with act or just Docker.

Common bugs and what surfaces them

Step is skipped unexpectedly → check the if: expression; act prints the resolved value.
Secret seems empty → it's not in scope (org / env mismatch) or it's a fork PR.
Cache never restores → key mismatch; run with debug to see the resolved key string.
Matrix produces no jobs → empty fromJSON input; check upstream job's output.
Self-hosted runner not picking up → label mismatch, runner offline, or runner busy.

Code

Always-upload diagnostic bundle on failure·yaml

      - name: Run e2e
        run: ./tests/e2e.sh
      - name: Diagnostic bundle
        if: always()
        run: |
          mkdir -p diag
          cp -r logs/ diag/
          docker compose logs > diag/compose.log 2>&1 || true
          env | sort | grep -v -i 'TOKEN\|KEY\|SECRET' > diag/env.log
      - if: always()
        uses: actions/upload-artifact@v4
        with:
          name: diag-${{ github.run_id }}-${{ github.run_attempt }}
          path: diag/
          retention-days: 7

The debug toolkit

Common bugs and what surfaces them

Code

External links

Exercise

Progress

Comments 0