Release

Release Skill — ngrok-operator

This skill orchestrates the full release preparation for the ngrok-operator. It supersedes the legacy workflow and is the canonical source for release steps; scripts/release.sh and .github/agents/release-agent.agent.md may still exist and delegate here.

The key insight: a shell script handles deterministic data gathering (PR metadata, file classification, author attribution via gh CLI), and you handle what AI is good at — summarizing changes into readable changelogs and suggesting version bumps.

The Three Components

A single PR often affects multiple components. The data-gathering script classifies by files changed — you don't need to figure this out yourself.

Workflow

Follow these steps in order. Do NOT commit, push, or create a PR — stop after local changes.

Step 1: Pre-flight checks

1. Verify git working tree is clean: git status --porcelain
2. Verify gh CLI is available and authenticated: gh auth status
3. Show current versions:
   • cat VERSION
   • yq '.version' helm/ngrok-operator/Chart.yaml
   • yq '.version' helm/ngrok-crds/Chart.yaml

If the tree isn't clean, stop and tell the user.

Step 2: Gather release data

Run the data-gathering script. It lives relative to this skill file:

bash .agents/skills/release/scripts/gather-release-data.sh > /tmp/release-data.json

If the user wants to override the base tags (e.g., to capture a wider range):

bash .agents/skills/release/scripts/gather-release-data.sh \
  --container-tag ngrok-operator-0.19.0 \
  > /tmp/release-data.json

Read the output JSON. Present a summary to the user:

• Number of PRs per component
• Whether any breaking changes were detected
• List the PR titles grouped by component

Step 3: Suggest version bumps

Analyze the PRs in the JSON to suggest next versions. Rules (this project uses semver, currently pre-1.0):

Container version (from VERSION):

• Breaking changes → bump minor (Y in 0.Y.Z)
• New features (feat: prefix in title) → bump minor
• Only fixes/chores/CI → bump patch (Z in 0.Y.Z)

Helm operator chart version (from Chart.yaml .version):

• Always bumped when releasing (it pins the container image version)
• Breaking Helm changes (removed values, renamed fields) → bump minor
• Otherwise → bump patch

CRDs chart version (from helm/ngrok-crds/Chart.yaml .version):

• Only bumped if PRs have new_for containing "helm_crds"
• Breaking CRD changes (removed fields, renamed CRDs) → bump minor
• Otherwise → bump patch
• If no CRD changes, skip entirely

Present your suggestions and ask the user to confirm or override. Wait for confirmation before proceeding.

Release candidates (RC): If the user asks for an RC, append -rc.N (with a dot before the number) to each version. The canonical format is always -rc.1, -rc.2, etc. — even if the user writes "RC1" or "rc1", normalize to -rc.N. To find the right N, check existing RC tags:

git tag -l 'ngrok-operator-<base-version>-rc.*' | sort -V | tail -1

If no RC exists yet, use -rc.1. Otherwise increment. Apply the RC suffix to all components being released.

When doing an RC:

• Branch name includes RC suffix: release-ngrok-operator-0.21.0-rc.1-helm-chart-0.23.0-rc.1
• VERSION file: 0.21.0-rc.1
• Chart.yaml versions: 0.23.0-rc.1
• Changelog entries: use the RC version as the section header (e.g., ## 0.21.0-rc.1)

When the user later does the final (non-RC) release, the RC changelog entries get folded into the final version entry — don't duplicate them.

Step 4: Create release branch

git fetch origin main
git checkout -b release-ngrok-operator-<app-ver>-helm-chart-<chart-ver> origin/main

Step 5: Update version files

1. Write new container version:

   echo "<new-app-version>" > VERSION

2. Update Helm operator chart:

   yq -Y -i ".version = \"<new-chart-version>\"" helm/ngrok-operator/Chart.yaml
   yq -Y -i ".appVersion = \"<new-app-version>\"" helm/ngrok-operator/Chart.yaml

3. If CRDs changed, update CRDs chart:

   yq -Y -i ".version = \"<new-crds-version>\"" helm/ngrok-crds/Chart.yaml
   yq -Y -i ".appVersion = \"<new-crds-version>\"" helm/ngrok-crds/Chart.yaml

4. If CRDs changed, update the dependency version in the operator chart:

   yq -Y -i "(.dependencies[] | select(.name == \"ngrok-crds\") | .version) = \"<new-crds-version>\"" helm/ngrok-operator/Chart.yaml

Step 6: Handle meta-only PRs

Some PRs only touch CI workflows, developer docs, AI agent configs, nix tooling, or other files that don't affect the released artifacts. The gather script marks these with "meta_only": true.

Review each meta-only PR and decide: include or exclude from the changelog.

Exclude when the PR clearly doesn't affect users:

• CI workflow tweaks (.github/workflows/ only)
• AI agent/copilot setup (.github/agents/, .github/copilot/)
• Nix devshell changes (flake.nix, flake.lock)
• Internal docs or specs (docs/developer-guide/, specs/)
• Makefile/tooling changes that don't affect the build output

Include when the change could matter to users even indirectly:

• Go version bumps (affects the built binary)
• Security docs users might reference
• Generated manifest changes (deploy/, manifest-bundle/)
• Test infrastructure changes that indicate behavior changes

Always err on the side of including — it's better to document something trivial than to miss something that matters.

Present excluded PRs to the user as a separate list with reasons, so they can override your decision:

Excluded from changelogs (meta-only):
- #786: Temporarily disabled Trivy scanning — CI workflow only
- #795: Consolidated nix setup — dev tooling only