release-gate

Files (4)

• SKILL.md
• profile.sh · scripts/
• release-check.sh · scripts/
• exit-codes.sh · tests/

SKILL.md (first lines)

# Pre-Release Gate

Systematic verification that a repository is ready to tag. Delegates all mechanical checks to a shell script and interprets its output.

## Script location

`~/.claude/skills/release-gate/scripts/release-check.sh`. It resolves the repo root via `git rev-parse --show-toplevel` and operates from there, so invoke it from anywhere inside the working tree.

## Prerequisites

`git`, `jq` and `gh` are always needed. The rest depend on the profile — `bun` for a Node or
Obsidian repo, `go` and `govulncheck` for a Go one, `task` where a Taskfile supplies the
commands. A missing binary makes its check row fail —
diagnose that as a setup gap, not a real gate failure.

## Run

```bash
~/.claude/skills/release-gate/scripts/release-check.sh [VERSION]
```

- Omit `VERSION` to check against whatever the repo's own version source reports. **This is the normal way to run it** — the no-argument form is what drives the two-run pipeline below.
- Pass `VERSION` (e.g. `1.5.0`) to verify readiness for a specific target version.

## Profiles

Most checks are the same in any repo. Five are not — dependencies, build,
tests, audit, and where the version lives — so those come from a profile the script detects
from the repo's shape:

| Detected on                                           | Profile         | Supplies                                                                                                                                       |
| ----------------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `manifest.json` with `minAppVersion` + `package.json` | Obsidian plugin | bun build/test/audit/outdated; a local gate of frozen install, build and test; version across `package.json`, `manifest.json`, `versions.json` |
| `package.json` alone                                  | Node            | the same without the local gate, version from `package.json` only; build and test only where those scripts exist                               |
| `go.mod`                                              | Go              | `go build`/`go test`/`govulncheck`, outdated via `go list -m -u` over the modules the build and tests link                                     |
| `Taskfile.yml` with a `test:` or `build:` target      | Taskfile        | `task test`, and `task build` when that target exists                                                                                          |

Any repo with `package.json` and `bun.lock` gets `bun install --frozen-lockfile` before the
build row, so the gate runs in a fresh linked worktree with no `node_modules`. A failed
install fails the build row.

Where no profile names a version source, the newest `## X.Y.Z` heading (also `## vX.Y.Z` or `## [X.Y.Z]`) in
`CHANGELOG.md` is the version. It is written at release prep, so before prep it names the
shipped version and the gate reports NOT STARTED. A repo with neither still needs a version
argument or a `.release-gate`.

Profiles compose — a Go repo with a Taskfile takes its build and test commands from the
Taskfile, which is what the fleet actually standardises on. Build and test are looked up
independently: a static site with a `build` target and no tests gets the first and skips the
second.

A `.release-gate` file in the repo root overrides any of it. It is sourced as shell:

```sh
VERSION_CMD="./cx --version"      # prints the version; first semver in stdout wins
VERSION_FILES="cx.js:grep"        # path[:spec] cross-checks — jq:<filter> | jqhas | grep
TEST_CMD="task test"              # any of DEPS_CMD BUILD_CMD TEST_CMD AUDIT_CMD GATE_CMD
TAG_PREFIX=v                      # normally detected from the most recent tag
RELEASE_MODE=tag                  # workflow | gh | tag — see below
DEPLOY_CMD="task deploy"          # detected from a deploy target; release-ship runs it
```

**Release mode** is how the ship makes the release. `workflow` means a `release.yml`
creates it on tag push. `gh` means `gh release create`. `tag` means the annotated tag
and the CHANGELOG are the release, and nothing is created on a forge. Off GitHub (origin
not on `github.com`) the default is `tag`, except for a repo with release assets, which
stays `gh`.

**`VERSION_CMD` has no fallback.** A repo whose version the script cannot find is refused
with exit `1` rather than guessed at. Defaulting to the last tag would make check 13
self-satisfying — the version would always equal a tag that exists — and every repo would
report NOT STARTED forever.

Anything a profile leaves empty makes its row **SKIP**, and skips are counted and named on
the result line. A gate that ran no tests must not be readable as "everything passed".

## Example output

```text
Pre-Release Gate: 2.1.0 (Taskfile (.release-gate))
==================================================

| #  | Check                  | Status | Details
|----|------------------------|--------|--------
| 1  | Deps current           | SKIP   | no dependency manifest
| 2  | Clean working tree     | PASS   |
| 3  | On default branch      | PASS   | main
| 4  | Up to date with remote | PASS   |
| 5  | No open PRs            | PASS   |
| 6  | Build                  | SKIP   | no build step
| 7  | Tests pass             | PASS   |
| 8  | Walkthrough snippets   | PASS   | 27 snippets match
| 9  | Dependency audit       | SKIP   | no audit command
| 10 | Version consistency    | PASS   | 2.1.0 across all files
| 11 | CHANGELOG entry        | SKIP   | no CHANGELOG.md
| 12 | Local gate             | PASS   | task check on a1b2c3d4
| 13 | Tag available          | PASS   | v2.1.0 not yet tagged
| 14 | Changes since last tag | INFO   | 8 commits since v2.0.0
| 15 | Clean after build      | SKIP   | no build step

Result: READY (0 failures, 0 warnings, 5 skipped)

Skipped: Deps current, Build, Dependency audit, CHANGELOG entry, Clean after build
```

Exit codes:

- `0` — all pass, ready to tag (`Result: READY`)
- `1` — one or more FAIL rows (`Result: BLOCKED`), or no version source could be found
- `2` — WARN rows only (`Result: WARNINGS`); not a green light, see below
- `3` — the release has not been prepared yet (`Result: NOT STARTED`); see below

On any FAIL or WARN, the script keeps the per-check log files and prints their location to stderr: `Release check logs preserved at: /var/folders/.../tmp.XXXX`. Open those logs when the details column points to a path inside.

## Where this sits in the pipeline

The gate runs **twice** per release, answering a different question each time:

1. **Before prep** — the current version is still the released one, so the gate exits

From philoserf/claude-code-config, MIT.

More from philoserf/claude-code-config