Release Workflow (codex-workspace-launcher)

This repo publishes the launcher image from the docker branch (see .github/workflows/publish.yml).

This project-specific workflow extends the base release-workflow with two non-negotiables:

1. •Record the pinned upstream pair (VERSIONS.env) in the release entry in CHANGELOG.md.
2. •Run local real-Docker E2E (full matrix) and abort if it fails.

Contract

Prereqs:

• •Run in this repo root.
• •Working tree is clean before running the E2E gate.
• •Docker is available (E2E is real Docker): docker info succeeds.
• •E2E environment is configured (via direnv/.envrc + .env, or equivalent).
  • •At minimum, repo-backed cases require CWS_E2E_PUBLIC_REPO.
  • •Auth-heavy cases require additional secrets/mounts (see DEVELOPMENT.md).
• •git available on PATH.
• •Optional (recommended): gh available + gh auth status succeeds (for tagging / releases / branch ops).

Inputs:

• •Release version: vX.Y.Z
• •Optional: release date (YYYY-MM-DD; defaults to today)
• •Optional: E2E image tag (defaults to cws-launcher:e2e)

Outputs:

• •CHANGELOG.md updated with a ## vX.Y.Z - YYYY-MM-DD entry that includes:
  • •### Upstream pins
    • •- zsh-kit: <ZSH_KIT_REF>
    • •- codex-kit: <CODEX_KIT_REF>
• •Local E2E run result (pass required; artifacts under out/tests/e2e/)
• •Optionally:
  • •Git tag vX.Y.Z pushed
  • •docker branch fast-forwarded to main to trigger publish

Stop conditions:

• •Local E2E fails: stop immediately; do not publish; report the failure output and ask how to proceed.
• •Changelog audit fails (missing pins / bad version heading / placeholders): stop; fix before publishing.

Key rule: E2E gate is mandatory

Run E2E before publishing and before any irreversible actions.

Recommended: run via direnv exec . so your .env is applied:

set -euo pipefail
set -a; source ./VERSIONS.env; set +a

direnv exec . ./scripts/bump_versions.sh \
  --zsh-kit-ref "$ZSH_KIT_REF" \
  --codex-kit-ref "$CODEX_KIT_REF" \
  --image-tag cws-launcher:e2e \
  --run-e2e

Notes:

• •--run-e2e forces CWS_E2E=1, CWS_E2E_FULL=1, and sets CWS_E2E_IMAGE=<image-tag>.
• •Destructive rm --all --yes coverage remains gated by CWS_E2E_ALLOW_RM_ALL=1.

Workflow

1. •

   Decide version + date

   • •Version: vX.Y.Z
   • •Date: YYYY-MM-DD (default: date +%Y-%m-%d)
2. •

   Run mandatory local E2E gate (real Docker)

   • •Use the command in “Key rule: E2E gate is mandatory” above.
   • •If it fails: stop and report (use .codex/skills/release-workflow/references/OUTPUT_TEMPLATE_BLOCKED.md).
3. •

   Prepare the changelog (records upstream pins)

   • •Use the helper that moves ## Unreleased into a new release entry and injects pins from VERSIONS.env:
     • •./scripts/release_prepare_changelog.sh --version vX.Y.Z
   • •Review CHANGELOG.md (fill out wording; remove - None if you added real bullets).
4. •

   Run required repo checks (per DEVELOPMENT.md)

   • •.venv/bin/python -m ruff format --check .
   • •.venv/bin/python -m ruff check .
   • •.venv/bin/python -m pytest -m script_smoke
5. •

   Commit the release notes

   • •Suggested message: chore(release): vX.Y.Z
   • •Do not run git commit directly; use the repo’s Semantic Commit helper (see AGENTS.md).
6. •

   Audit (strict)

   • •Run after committing (audit requires a clean working tree):
     • •./scripts/release_audit.sh --version vX.Y.Z --branch main --strict
7. •

   (Optional) Tag the release

   • •Create: git tag vX.Y.Z
   • •Push: git push origin vX.Y.Z
   • •Optional GitHub Release:
     • •Extract notes from CHANGELOG.md and publish with gh release create.
8. •

   Publish images (this repo’s publish trigger)

   • •Fast-forward docker to main and push:
     • •git fetch origin
     • •git checkout docker
     • •git merge --ff-only origin/main
     • •git push origin docker
     • •git checkout main
9. •

   Verify publish

   • •Follow docs/runbooks/INTEGRATION_TEST.md (record the workflow run URL + tags evidence).

Helper scripts (project)

• •Prepare changelog + inject upstream pins: scripts/release_prepare_changelog.sh
• •Audit changelog entry (pins + basic release checks): scripts/release_audit.sh
• •Build + verify + local E2E (full matrix): scripts/bump_versions.sh --run-e2e

Output templates

• •Success: .codex/skills/release-workflow/references/OUTPUT_TEMPLATE.md
• •Blocked: .codex/skills/release-workflow/references/OUTPUT_TEMPLATE_BLOCKED.md