# Managing Release Issue

> Maintain a phased production release checklist in a GitHub issue. Use when a user finishes configuring a service, environment, or integration outside production and wants to record its production counterpart, asks to update a release issue or checklist, or prepares production steps for a release.

- Skill: `ilya-valasiuk/managing-release-issue` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ilya-valasiuk/managing-release-issue`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ilya-valasiuk/managing-release-issue/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: ilya-valasiuk (https://skillmd.com/u/ilya-valasiuk)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ilya-valasiuk/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:

```bash
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:

```bash
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.