GreptimeDB Release Runbook

Publish a formal GreptimeDB release on GreptimeTeam/greptimedb. Always operate against that repo (for gh, pass --repo GreptimeTeam/greptimedb). Changelog generation is a separate, involved task — use the greptimedb-release-note skill for it.

This whole flow touches public infrastructure. Confirm with the user before the outward-facing step (creating the release, which creates the tag and triggers CI).

Prerequisites & remote

• Tools: gh (check with gh auth status) and git. Changelog generation additionally needs git cliff and Python — see the greptimedb-release-note skill.
• Resolve the remote first. This runbook writes <remote> for the git remote pointing at GreptimeTeam/greptimedb; substitute your actual name (often upstream, sometimes origin on a direct clone):

  git remote -v | grep -i 'GreptimeTeam/greptimedb' | awk '{print $1}' | head -1

0. Inputs: version and branch

• Ask the user for the version to release (e.g. 1.1.0, 1.0.3) and, if needed, the branch.
• Branch is inferred from version: MAJOR.MINOR → release/v<MAJOR>.<MINOR>.
  • v1.0.0 / v1.0.1 / v1.0.2 live on release/v1.0; v1.1.0 lives on release/v1.1.
  • Infer it, then double-check with the user.
• New minor/major (X.Y.0) is cut from main. If release/vX.Y does not exist on the remote, offer to create it from the intended main commit (with the user's consent): git push <remote> <commit>:refs/heads/release/vX.Y.
• Patch (X.Y.Z, Z>0) must use the existing release/vX.Y branch (it carries cherry-picked commits).
• Check what exists on the remote: git ls-remote --heads <remote> 'release/*'.

1. Verify the Cargo version

The workspace version on the release branch must equal the version being released, or stop. Fetch the branch first, then read FETCH_HEAD directly — git fetch <remote> release/vX.Y only opportunistically updates the remote-tracking ref <remote>/release/vX.Y (and only when the remote has a matching configured refspec), so it may be missing or stale (e.g. a custom <remote>, or a branch just created in §0). Reading FETCH_HEAD always reflects the tip just fetched:

git fetch <remote> release/vX.Y
git show FETCH_HEAD:Cargo.toml | grep -A30 '\[workspace.package\]' | grep -m1 version

(For a fresh minor cut from main, <remote>/main and release/vX.Y are usually the same commit.)

2. Generate and curate the changelog

Use the greptimedb-release-note skill. It produces CHANGELOG-vX.Y.Z.md (uncommitted) and the docs-blog variant. Review the highlights with the user and iterate before publishing.

3. Create the GitHub release (creates the tag + triggers CI)

Do NOT pre-create the tag. Creating the release creates the tag and fires the tag-push CI (.github/workflows/release.yml) that builds all binaries (~hours). Confirm with the user, then:

gh release create vX.Y.Z \
  --repo GreptimeTeam/greptimedb \
  --target release/vX.Y \
  --title "Release vX.Y.Z" \
  --notes-file CHANGELOG-vX.Y.Z.md \
  --prerelease

• Title convention: Release vX.Y.Z.
• Always create as --prerelease: prerelease here is just a "build in progress" marker. The CI clears it on success (see §5). (The user creating it on the web works too.)
• Verify: gh release view vX.Y.Z --repo GreptimeTeam/greptimedb --json name,tagName,isPrerelease,draft,targetCommitish.

4. Open the docs release-note PR (do not wait for CI)

Right after triggering the release, open the docs draft PR (see the docs section of the greptimedb-release-note skill). It only needs the finalized changelog.

Then delete the local CHANGELOG-vX.Y.Z.md (its content now lives in the release body and the docs blog post).

5. After the CI build finishes (~hours)

CI's publish-github-release action, for a tag matching ^vX.Y.Z$, runs ncipollo/release-action with allowUpdates: true, prerelease=false, makeLatest=true, omitBody=true (so it keeps our changelog body but finalizes the flags). These flags are described from the current .github/workflows/release.yml — verify against the workflow if behavior differs. Verify success:

gh release view vX.Y.Z --repo GreptimeTeam/greptimedb --json isPrerelease,assets

Latest handling is conditional on whether this is the newest version:

• Releasing the latest version (e.g. v1.1.0 when nothing newer exists) → CI's finalized state (non-prerelease, latest) is correct; do nothing.
• Releasing a non-latest line (e.g. a patch v1.0.3 while v1.1.0 is already latest) → set it back to non-latest after CI finishes: gh release edit vX.Y.Z --repo GreptimeTeam/greptimedb --latest=false.

6. Rollback (only on failure, with double confirmation)

Show the user exactly what will be removed first; never delete blindly.

gh release delete vX.Y.Z --repo GreptimeTeam/greptimedb   # remove the release
git push <remote> :refs/tags/vX.Y.Z                        # remove the tag

Conventions / gotchas

• Remotes: <remote> is whatever points at GreptimeTeam/greptimedb (see Prerequisites). gh defaults can be unreliable in a repo with many remotes — always pass --repo GreptimeTeam/greptimedb.
• Release title is always Release vX.Y.Z.
• When reasoning about "previous version", skip nightly / build-suffixed tags (*-nightly-*, vX.Y.Z-rc.N-<sha>-<date>-*).