gh-release

# gh-release Cut a release directly from a release branch. Do not open a release PR, merge the release branch into `main`, or advance `main` to record a release. Follow the version policy in `CONTRIBUTING.md`. ## Choose the version and branch Parse `$ARGUMENTS` as `<tag> [<commit>]`. Tags are bare public versions without `v`: `1.2.0-alpha.1`, `1.2.0-alpha.1.1`, `1.2.0-rc.1`, `1.2.0`, or `1.2.1`. Validate numeric components without leading zeros. Prereleases use `alpha.N`, `alpha.N.M` (a hotfix of alpha `N`), or `rc.N` and only attach to a `.0`. Stable patches increment the patch component. If no tag was given, inspect published releases and ask which version to cut. Do not infer permission to publish from a request to inspect or prepare a release. - Before freeze, a new alpha `X.Y.0-alpha.N` starts from the chosen merged `main` commit (default `origin/main`) on `release/X.Y.0-alpha.N`. - An alpha hotfix `X.Y.0-alpha.N.M` reuses `release/X.Y.0-alpha.N`. Require the existing branch and a published alpha on that line; no stable release is required. Cherry-pick fixes onto it and add successive immutable tags. Never create a branch per hotfix or start the hotfix from newer `main` code. For example, `1.1.0-alpha.1.1` and `1.1.0-alpha.1.2` both use `release/1.1.0-alpha.1`; `1.1.0-alpha.2` starts a new alpha line from `main`. - At freeze, create `release/<major>.<minor>` from the chosen merged `main` commit. RCs, stable minors, and subsequent patches use that train branch. - For an existing alpha line or frozen train, default to its current remote tip. An explicit commit must be that tip; prepare any required cherry-picks separately first. Never reset a release branch to `main` or create a patch branch from newer trunk code. - A stable patch requires an existing train branch and a published stable release on that train. - Both alpha hotfixes and stable patches contain fixes that landed on `main` first and were cherry-picked onto the release branch. Verify the full diff from the previous release: no migration changes, database-schema changes, backfills, or new registry actions. If a fix depends on those changes, exclude it rather than pulling its feature dependencies into the patch. Resolve the selected commit to an immutable `COMMIT_SHA` and the branch to `BRANCH`. A new alpha line's base or a new train's base must be reachable from `origin/main`; hotfix commits instead descend from their release branch and retain the source commits' cherry-pick provenance. Do not release an unmerged PR. Check the selected commit's CI and stop on missing or failing evidence unless the user explicitly accepts it. Verify the selected branch contains the stable-only image guard and the current release workflow before cutting its tag; old train branches may need those changes cherry-picked first. ## Preflight and confirmation Fetch branches and tags, inspect the working tree, and verify the public tag is absent locally, remotely, and from GitHub releases. Distinguish a missing release from an API/authentication error. If the tag exists, stop; never move it. A new alpha line's branch must be absent remotely and locally. For an alpha hotfix or an existing frozen train, reuse the existing release branch; create a train branch only at its initial freeze. Preserve any prepared local cherry-picks and verify they fast-forward the remote tip before pushing. Use an isolated worktree if the branch is checked out elsewhere. Do not stash, reset, or overwrite unrelated working changes. ### Strict invariant: patches cannot contain database migrations Every patch release, including alpha hotfixes (`X.Y.0-alpha.N.M`) and stable patches (`X.Y.Z`, where `Z > 0`), must pass this gate before any version bump, release commit, push, tag, image build/rebuild, or publication. Prerelease status does not exempt a patch. Never deploy a patch that violates this invariant; deployment remains outside this skill's scope. Resolve and pin `PREV_TAG` using the published-release baseline rules in **Release notes** below, before mutation. Require it to be an ancestor of `COMMIT_SHA`. Compare the complete release trees, not just the latest commit or the cherry-picked fixes: ```sh git diff --name-status "$PREV_TAG" "$COMMIT_SHA" -- alembic/versions/ git diff "$PREV_TAG" "$COMMIT_SHA" ``` Any added, modified, deleted, or renamed migration is a hard blocker, including edits to an already-published migration. Inspect the full diff for migrations outside that directory, database-schema changes, and data backfills; those also block the patch. Existing migrations unchanged from the baseline are allowed. If the baseline or inspection cannot be verified, stop. On a blocker, refuse the patch release and report the baseline, candidate SHA, and offending files. Release approval, urgency, successful CI, or claims that a migration is safe do not waive this invariant. Exclude the change and its dependencies from the patch, or propose a separately approved non-patch release. Never silently change the requested version to bypass the gate. Before mutation, show: - Base commit and CI evidence; branch to create or reuse. - For a patch, the pinned baseline and evidence that the migration gate passed. - Public tag and whether the GitHub release is stable or a prerelease. - Version-bump, branch-push, tag-push, and release-publication commands. - Stable image tags update `X.Y` and `latest` unless the version a tag points to is newer (an equal version is re-published), so an older train's hotfix moves only its `X.Y` tag. Prereleases leave `latest` unchanged. - Whether the GitHub release is marked latest: only when the tag is higher than every published stable release, because the Compose docs download `releases/latest/download/<file>`. - The Compose install files attached at publication, with `docker-compose.yml` pinned to the tag's image. Wait for explicit confirmation unless the user already approved this exact release plan. Approval to merge or fix a PR is not release authorization. ## Bump, commit, and tag Create or switch to `BRANCH` at the verified commit. Run `just update-version <tag>` and answer its overwrite prompt only for the approved release. It writes the public tag to `__version__` and its PEP 440 value to `__pep440_version__` (for example, `1.2.0-alpha.1` becomes `1.2.0a1`, and `1.2.0-alpha.1.2` becomes `1.2.0a1.post2`). Verify both application and registry versions agree, and validate the Python version with `packaging.version.Version` through `uv run python`. Review the generated diff and, for a patch, repeat the migration gate against the final release tree (including all version-bump edits) before committing or pushing. Stage only the changed files individually, and create a signed `release: <tag>` commit. Never bypass hooks or signing. Push `BRANCH`. For a prerelease or an older train's hotfix, record the current `latest` digests of all three images before pushing the tag. Create an annotated `<tag>` on the version-bump commit and push it. No merge to `main` is involved. Leave the branch in place. ## Verify the images before publication Tag push triggers `.github/workflows/build-push-images.yml`. Find the run whose tag and `headSha` match the new release commit, then watch it to successful completion. Inspect all three multi-platform manifests (`tracecat`, `tracecat-ui` and `tracecat-tunnel-gateway`) and their version/revision labels. For a prerelease or an older train's hotfix, compare all three `latest` digests before and after the build; for the highest stable release, verify `X.Y` and `latest` point to the new image manifests. For a stable hotfix on an older train, verify its `X.Y` moved and `latest` did not; a prerelease moves neither. If image publication fails, stop before creating the GitHub release. Report the existing branch/tag and failed run; never move the tag or automatically cut a replacement. To rebuild, use a separate trusted, updated `main` checkout and run: ```sh uv run python scripts/rebuild_release_images.py '<tag>' ``` The helper requires the remote tag's workflow to exactly match the committed publisher in that checkout before dispatching with the tag as both ref and input. An older tag runs its own historical workflow, so guards on `main` cannot protect a direct dispatch or rerun. On a mismatch or lookup failure, stop; never bypass the helper or move the tag. A new release containing the current publisher requires a separately approved release plan. For a retry, verify the run ID, event, and release commit rather than accepting an older successful run. Rebuilding an older patch leaves both `X.Y` and `latest` unchanged. ## Release notes Resolve `PREV_TAG` from published releases, paginating the full list. For an alpha hotfix, use the previous published hotfix on the same `alpha.N` line, or its original alpha tag for the first hotfix. For `1.1.0-alpha.1.2`, the baseline is `1.1.0-alpha.1.1`, even if `1.1.0-alpha.2` has already shipped. Verify the baseline is an ancestor of the selected release commit. For other releases, use the previous version on the same major/minor train, ordered by semantic version (alpha before RC before stable, then patches). For the first alpha of a new train, use the preceding stable version. If a train skips alphas, its first release also uses the preceding stable version. Never pick an unrelated train merely because it was published most recently. If there is no unambiguous baseline, ask before publication. Pin the range to `PREV_TAG..<tag>`. The draft maintained on `main` is not a release branch's changelog; do not publish or consume that draft. Generate raw notes with explicit `tag_name`, `previous_tag_name`, and the version-bump commit as `target_commitish`: ```sh REPO=$(gh repo view --json nameWithOwner --jq .nameWithOwner) RAW_NOTES=$(gh api "repos/$REPO/releases/generate-notes" \ --method POST \ -f tag_name='<tag>' \ -f previous_tag_name="$PREV_TAG" \ -f target_commitish='<release-commit>') ``` Extract PR numbers from the returned body and retrieve their titles and labels. For cherry-picked fixes, verify that the notes include the original merged PRs represented in the commit range, even if GitHub omits their associations. Read `.github/release-drafter.yml` and derive the buckets from it. Do not copy the category list into this skill: the last copy drifted, and a stale copy silently files changes under headings the real release notes do not have. From that file you need: - `exclude-labels`: drop any PR carrying one of these. - `categories`, in order: bucket each remaining PR into the **first** category whose `labels` intersect the PR's labels. Use the category's `title` verbatim. Anything left with no matching label goes under a trailing **Other** section. Do not silently drop PRs. Format each entry as `- <title> (#<number>)`, matching the config's `change-template`, then apply every rule in the config's `replacers:` to the assembled body, in order. Read them from the file the way you read `categories:`; do not restate them here. They are not cosmetic, and they are not only scope aliases. They rewrite the type prefix too -- `chore(deps)` and `fix(deps)` become `build(deps)`, a scope that merely repeats its type is dropped, `feat!(api)` moves the bang to `feat(api)!` -- and they capitalize the first letter of most descriptions. Three shapes are spared, and the config lists them: a first word holding `_` or `.`, a first word with a capital after its first letter, and an explicit list of lowercase names that must not be Title-cased. Read the guard from the file rather than reasoning about which of the three applies. Skip the replacers and this skill's output disagrees with the stable release notes for the same commits. ## Publish and report Write the categorized Markdown and a `PREV_TAG...<tag>` comparison link to a temporary notes file. Releases are immutable once published, so attach the Docker Compose install files in the same `gh release create` call; they cannot be added later. Stage them from the tag's tree, not the working tree: ```sh ASSET_DIR=$(mktemp -d) for f in docker-compose.sandbox.yml env.sh env-migration.sh Caddyfile; do git show "<tag>:$f" > "$ASSET_DIR/$f" done # GitHub renames leading-dot assets, so publish the template as env.example. git show '<tag>:.env.example' > "$ASSET_DIR/env.example" # Pin the release's Compose file to its own image, so it never pairs with # another train's `latest` image. Release branches may already carry the tag. git show '<tag>:docker-compose.yml' | sed 's/${TRACECAT__IMAGE_TAG:-latest}/${TRACECAT__IMAGE_TAG:-<tag>}/g' \ > "$ASSET_DIR/docker-compose.yml" rg -oN --no-filename 'TRACECAT__IMAGE_TAG:-[^}]*' "$ASSET_DIR/docker-compose.yml" | sort -u find "$ASSET_DIR" -type f -size +0 | wc -l ``` Stop unless the `rg` line prints exactly `TRACECAT__IMAGE_TAG:-<tag>` and the count is `6`. A missing file at the tag leaves an empty asset, which the count catches. All six files exist at every release tag since 1.1.0. Publish the existing tag using `--verify-tag`, so a typo cannot create a tag on the default branch. `gh` uploads the files to a draft and then publishes it: ```sh # Stable release: mark it latest only when it is higher than every published # stable release, so an older train's patch never takes over the docs' # releases/latest download links. Unpublished tags and drafts do not count. HIGHEST_PUBLISHED=$(gh release list --exclude-drafts --exclude-pre-releases \ --limit 1000 --json tagName --jq '.[].tagName' | rg '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -n 1) echo "highest published stable: ${HIGHEST_PUBLISHED:?no published stable releases listed; stop}" HIGHEST_STABLE=$(printf '%s\n' "$HIGHEST_PUBLISHED" '<tag>' | sort -V | tail -n 1) if [ "$HIGHEST_STABLE" = '<tag>' ]; then LATEST_FLAG=--latest; else LATEST_FLAG=--latest=false; fi gh release create '<tag>' "$ASSET_DIR"/* --verify-tag "$LATEST_FLAG" \ --title 'Tracecat <tag>' --notes-file "$BODY_FILE" # Prerelease: gh release create '<tag>' "$ASSET_DIR"/* --verify-tag --prerelease --latest=false \ --title 'Tracecat <tag>' --notes-file "$BODY_FILE" ``` If the stable `echo` fails, stop: an empty `HIGHEST_PUBLISHED` means `gh release list` failed. After publishing, confirm with `gh release view '<tag>' --json assets` that all six assets are attached. Run only the command for the approved release type. If the range contains no changes, state `No changes since <PREV_TAG>.` rather than reusing older notes. Report the branch, immutable tag/commit, GitHub release URL, image-build run, and manifest verification. Never delete the alpha-line or train branch, force-push, amend existing release commits, or deploy as part of this skill. If signing or a publication step fails, stop and report the concrete state before attempting further external mutations.