github-actions-public-ci-diagnostics

GitHub Actions Public CI Diagnostics

Use this when a remote GitHub Actions run fails but local tests pass, full job logs are unavailable, or the failure only appears on ubuntu-latest/matrix runners.

Workflow

1. Check local rules first

   • Inspect project agent rules before changing files.
   • Run the same local quality gates the workflow claims to run.
   • Keep unrelated dirty files out of staging.

2. Map the remote failure without secrets

   • Use public REST endpoints first:
     • /repos/{owner}/{repo}/actions/runs?head_sha={sha}
     • /repos/{owner}/{repo}/actions/runs/{run_id}/jobs
     • /repos/{owner}/{repo}/commits/{sha}/check-runs
     • /repos/{owner}/{repo}/check-runs/{check_run_id}/annotations
   • If /actions/jobs/{job_id}/logs returns 403 Must have admin rights to Repository, do not guess from missing logs. Treat it as an observability gap.
   • Record the failing workflow, job, step, Python version, event, ref, and exact annotation text.

3. Add public failure annotations before blind fixes

   • If annotations only say Process completed with exit code 1, add a small repository script that runs pytest, captures stdout/stderr as UTF-8, prints normal output, and emits a GitHub annotation such as ::error title=pytest failed::... on failure.
   • Use a workspace-local pytest temp dir and disable cache when sandbox or CI permissions may differ, for example python -m pytest -q -p no:cacheprovider --basetemp=.pytest-tmp-ci --tb=short --maxfail=1.
   • Wire both quality and publish workflows through the same helper so tag-push release failures are diagnosable too.
   • Add tests asserting the workflows call the helper and the helper contains annotation and step-summary markers.

4. Reproduce by failure layer

   • First compare workflow order: install, lint, test, build, metadata, release boundary, publish.
   • If tests pass locally but fail on Linux, inspect OS-specific paths, case sensitivity, executable names, path separators, temp/cache directories, locale/encoding, and Python matrix versions.
   • For venv smoke tests, fixtures must create both Windows Scripts/python.exe plus Scripts/tool.exe and POSIX bin/python plus bin/tool when the production code chooses paths by os.name.
   • Do not treat a Windows-only fixture as proof that Linux CI is broken.