Release Checklist

简体中文

Use this checklist when preparing a tagged release. For v0.2.0, the release tag is expected to publish a GitHub Release and container images to GHCR through the GitHub Actions release workflow. PyPI publishing is gated until the PyPI project and trusted publishing configuration are ready.

Do not create or push a release tag until the maintainer explicitly approves the release.

Preflight

• Confirm the working tree is clean: git status --short --branch.
• Fetch tags before checking release state: git fetch --tags origin.
• Confirm the target tag does not already exist locally or remotely: git tag --list v0.2.0 and git ls-remote --tags origin 'refs/tags/v0.2.0'.
• Confirm pyproject.toml, src/codex_quota_monitor/version.py, default.nix, CHANGELOG.md, and public docs all describe the same version.
• Confirm GitHub Actions CI is green on the commit that will be tagged.
• Confirm the Pages workflow is green on the current main commit and the gh-pages branch contains the generated HTML site for that commit.
• Confirm GHCR does not already contain the target version.
• Confirm the pinned Docker base image digest is current enough for the release.
• Review security self-audit and threat model for any API, metrics, history, benchmark, log, network, or deployment-behavior change in the release.
• If this release should publish to PyPI, configure PyPI trusted publishing for owner xsyxnx, repository codex-quota-monitor, workflow release.yml, environment pypi, and project name codex-quota-monitor; then set the repository variable PYPI_PUBLISH_ENABLED=true before pushing the tag.

Local Validation

Run these from the repository root before tagging:

nix develop -c python3 -m unittest discover -s tests -v
nix develop -c python3 -m build
nix build .#codex-quota-monitor --no-link
nix run .#codex-quota-monitor -- --help
nix run .#codex-quota-monitor -- --version
nix run .#codex-quota-monitor -- init --mode user >/tmp/cqm-init.txt
nix run .#codex-quota-monitor -- print-config --state-db off
printf 'state_db = "off"\ndisplay_timezone = "UTC"\n' >/tmp/cqm-config.toml
nix run .#codex-quota-monitor -- print-config --config /tmp/cqm-config.toml
nix run .#codex-quota-monitor -- doctor --json --management-base-url http://127.0.0.1:9 --gateway-health-url http://127.0.0.1:9/healthz --state-db off >/tmp/cqm-doctor.json || test "$?" -eq 1
printf '{"access_token":"secret","account_id":"acct-a"}\n' >/tmp/cqm-secret.json
nix run .#codex-quota-monitor -- redact /tmp/cqm-secret.json --secret secret >/tmp/cqm-redacted.json
! grep -q secret /tmp/cqm-redacted.json
nix run .#codex-quota-benchmark -- --help

The intentionally unreachable doctor command should return a JSON payload with clear fail checks instead of a traceback.

If Docker is available locally, also run:

docker build -t codex-quota-monitor:release-check .
docker run --rm codex-quota-monitor:release-check --help
./scripts/ci/smoke-docker-image.sh codex-quota-monitor:release-check cqm-release-check

If Docker is not available locally, treat the Docker job in GitHub Actions as the blocking image validation gate.

Tag And Publish

Only after approval, create an annotated tag and push it:

git tag -a v0.2.0 -m "codex-quota-monitor v0.2.0"
git push origin v0.2.0

The tag push triggers .github/workflows/release.yml, which should:

• build and smoke-test the Python wheel and sdist;
• attach distributions to a GitHub Release;
• publish to PyPI using trusted publishing only when PYPI_PUBLISH_ENABLED=true;
• publish GHCR images tagged 0.2.0 and 0.2;
• attach SBOM and provenance attestations to the GHCR image;
• sign the pushed GHCR image digest with keyless cosign.

Post-publish Checks

• GitHub Release exists for v0.2.0 and includes the built distributions.
• If PYPI_PUBLISH_ENABLED=true, PyPI exposes codex-quota-monitor==0.2.0.
• If PyPI was published, uv tool install codex-quota-monitor==0.2.0 can run codex-quota-monitor --help, codex-quota-monitor --version, codex-quota-monitor init --mode user, codex-quota-monitor print-config, and codex-quota-benchmark --help.
• If PyPI was published, pipx install codex-quota-monitor==0.2.0 works as a compatibility path.
• GHCR exposes ghcr.io/xsyxnx/codex-quota-monitor:0.2.0 and :0.2.

• GHCR exposes SBOM/provenance attestations, and this keyless verification succeeds:

  cosign verify \
    --certificate-oidc-issuer https://token.actions.githubusercontent.com \
    --certificate-identity-regexp 'https://github.com/xsyxnx/codex-quota-monitor/.github/workflows/release.yml@refs/tags/v.*' \
    ghcr.io/xsyxnx/codex-quota-monitor@<digest>
  

• nix run github:xsyxnx/codex-quota-monitor/v0.2.0#codex-quota-monitor -- --help works.

• The website links for quick start, install, troubleshooting, upgrade, agent discovery, use cases, and this checklist return 200:

  for path in /quick-start.html /install.html /troubleshooting.html /upgrade.html \
    /agent-discovery.html /use-cases.html /release-checklist.html \
    /forum-post-v0.2.0.html /forum-post-v0.2.0.zh-CN.html; do
    curl -fsSIL "https://xsyxnx.github.io/codex-quota-monitor${path}" >/dev/null
  done
  

• Rootless user service, config file, and reverse-proxy examples are present in the release source tree.
• The forum post draft points at only published artifacts and current support contacts.

Stop Conditions

• Version metadata disagrees between package, Nix, changelog, or docs.
• Local tests or Nix package/app smoke tests fail.
• The target tag or GHCR version already exists.
• PyPI publishing is expected, but the PyPI version already exists or trusted publishing is not configured.
• GitHub Actions release workflow fails before all release artifacts are published.
• PyPI or GHCR publishing succeeds only partially and the visible install instructions would point users at missing artifacts.
• GHCR image signing, SBOM, or provenance generation fails.