Managing Release Issue

Managing the Release Issue

Use a GitHub issue as the living checklist of everything that must be done on the production side before a release.

Keep the target release issue accurate as development progresses. Resolve the repository, issue number, non-production environment, production environment, and release route from the user's request, repository instructions, or established conversation context. If the target repository or issue remains unclear, ask before making changes.

The Core Rule

Only add a production step once its equivalent is already working in the project's relevant non-production environment.

The issue is not a wishlist. When the user has integrated and verified a service, environment change, configuration value, domain, or other capability outside production, add its production counterpart. This keeps the checklist trustworthy: every unchecked box is a real, known action.

If the user asks to add a step for something that is not yet working in the relevant non-production environment, confirm that before adding it.

Issue Structure

Organize the release issue into these phases and keep new steps in the right phase. If the issue already uses equivalent headings, preserve its wording and structure.

• Phase 1 — Infrastructure: production counterparts of databases, storage, domains, secrets, environment configuration, and external services.
• Phase 2 — Application Readiness: required features and project verification such as lint, typecheck, integration tests, and end-to-end tests.
• Phase 3 — Pre-Release Smoke Test: manual checks against the designated non-production deployment before starting the release.
• Phase 4 — Release: the release PR or equivalent promotion, CI, merge, production deployment, migrations, and other release actions.
• Phase 5 — Post-Release Verification: checks against the live production domain.
• Environment Variables — Production Master List: a table of every secret/env var required in production.

When a new integration adds an env var or secret, add it to both the relevant phase (as an action) and the env var table.

Workflow

1. Understand what changed outside production. Ask what was configured and confirm it works in the relevant non-production environment. Identify whether it needs a production environment variable or secret, a manual setup step, a release action, or a verification step, and which phases it touches.

2. Read the current issue body so you edit against the latest state, not a stale copy:

gh issue view <issue-number> --repo <owner/repo> --json title,body,url

3. Insert the new step(s) into the correct phase, matching the existing style exactly:

   • Use - [ ] checkboxes.
   • Phrase steps as concrete, verifiable production actions (e.g. "SERVICE_API_KEY set in the production environment").
   • Reference file and configuration names in backticks where helpful.
   • Add any new env var/secret to the Environment Variables table too.
   • Avoid duplication — if a check already exists in another phase (e.g. an upload smoke test), don't repeat it.

4. Write the updated body back. Preserve everything already there; only add or refine. Use a heredoc so formatting stays intact:

gh issue edit <issue-number> --repo <owner/repo> --body "$(cat <<'BODY'
<full updated issue body>
BODY
)"

5. Confirm to the user what was added and to which phase, and return the issue URL.

Style Notes

• Keep it lean and production-focused. Do not turn non-production-only concerns into production steps.
• Don't add "review the plan / connection limits" style vague items — steps should be actionable and checkable.
• Match the terse, imperative tone of the existing checklist.
• Only modify the identified release issue. Don't touch other issues or push code unless the user explicitly asks.