Publish troubleshooting guide for common CI failures #23
Description
Summary
Author a troubleshooting guide covering frequent CI issues: missing runner versions, cache pitfalls, failed tag lookups, and security gate skips. Link to versions manifests and setup-python references.
Why
When the action skips or fails, users need actionable steps. Centralizing guidance reduces support load and accelerates fixes.
What needs to happen
- Compile common failure modes from issues/support history (runner availability, registry misses, cache misses, etc.).
- Document root causes, mitigation steps, and relevant links (versions manifest, setup-python docs, etc.).
- Ensure the guide stays updated as new features (runner gate, registry checks) land.
- Link the guide from README and PR templates if helpful.
References
- Roadmap quality item: "Troubleshooting guide".
- https://github.com/actions/python-versions
- https://github.com/actions/setup-python
Acceptance criteria
- Troubleshooting guide exists in docs with discrete sections per failure mode.
- README or contributing docs link to the guide.
- Content references authoritative upstream docs for runner versions and setup guidance.