| 1 | # GitHub Automation DOX |
| 2 | |
| 3 | ## Purpose |
| 4 | |
| 5 | - Own repository automation that runs on GitHub, including workflows and release-planning scripts. |
| 6 | - Keep CI, Docker publishing, stale issue handling, and release-note generation aligned with repository release rules. |
| 7 | |
| 8 | ## Ownership |
| 9 | |
| 10 | - `workflows/` contains GitHub Actions workflow definitions. |
| 11 | - `scripts/` contains Python helpers called by workflows. |
| 12 | - This file owns release automation rules; user-facing release documentation belongs under `docs/`. |
| 13 | |
| 14 | ## Local Contracts |
| 15 | |
| 16 | - Docker publishing lives in `workflows/docker-publish.yml` and delegates planning to `scripts/docker_release_plan.py`. |
| 17 | - Releasable tags are `vX.Y` tags at or above `v1.0`, matching the workflow environment. |
| 18 | - On `main`, the newest eligible tag publishes both the version tag and `latest`, then creates or updates its GitHub release after the image push succeeds; other allowed branches publish only their branch tag. |
| 19 | - Manual dispatch without a tag backfills missing Docker Hub tags. Manual dispatch with a tag rebuilds that target and refreshes `latest` and the GitHub release only when it remains the newest eligible tag on `main`. |
| 20 | - Release-note generation reads `scripts/openrouter_release_notes_system_prompt.md` from the repository root and requires OpenRouter credentials from workflow environment variables. |
| 21 | - Release notes compare against the previous published GitHub release tag and fall back to `No release notes.` when no meaningful summary is generated. |
| 22 | - Keep workflow secrets in GitHub Actions secrets or environment variables. Do not commit credentials, tokens, or generated release bodies containing private data. |
| 23 | - Workflow scripts must fail loudly with actionable messages when required environment variables or git refs are missing. |
| 24 | |
| 25 | ## Work Guidance |
| 26 | |
| 27 | - Prefer deterministic, testable Python for workflow planning logic instead of complex inline shell in YAML. |
| 28 | - Preserve manual dispatch behavior when changing Docker publishing. |
| 29 | - Keep branch, tag, and release behavior synchronized between workflow YAML, release scripts, tests, and user-facing release documentation. |
| 30 | |
| 31 | ## Verification |
| 32 | |
| 33 | - Run `pytest tests/test_docker_release_plan.py` after changing Docker publish planning or release workflow behavior. |
| 34 | - Run targeted tests for any changed script that already has coverage. |
| 35 | |
| 36 | ## Child DOX Index |
| 37 | |
| 38 | No child DOX files. |