# Github Release

> Cut, verify, and reconcile immutable GitHub releases with the socket-release kit - the registry-resolvability ORDER RULE, the three-step draft-upload-undraft cut, checksums.txt production, and tag-gap healing. Use when tagging a release, healing a missing tag/release, or when the github-release workflow gate refuses a tag.

- Skill: `socketdev/github-release` (Agent Skill)
- Install (CLI): `npx skillmds@latest add socketdev/github-release`
- Raw SKILL.md: https://api.skillmd.com/api/skills/socketdev/github-release/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: socketdev (https://skillmd.com/u/socketdev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/socketdev/github-release

---


# GitHub release (immutable, registry-gated)

ORDER RULE (non-negotiable): the immutable GitHub release is the FINAL
marker of a release. It can only follow a version that already resolves on
its registry - never precede one. `requireRegistryLive` enforces this in
every path; the `github-release.yml` workflow's `gate` job refuses a pushed
tag whose version is not live (`registry-liveness-gate.mjs`, zero-dep, runs
before any install).

## Normal path (automatic)

The npm/cargo promote tail cuts the tag + release itself: after
`node scripts/socket-release/npm-publish.mts --approve` promotes and the
version resolves live, the engine tags `v<version>`, pushes the tag, and
cuts the release. Nothing to run by hand when that succeeds.

## Cutting a release with assets

`github-release.mts --release` performs the fleet-canonical three-step immutable
cut - `gh release create --draft --verify-tag` → upload assets → `gh release
edit --draft=false` — and writes a `checksums.txt` manifest (sha1 + sha256 +
sha512) alongside the tarball, so the GitHub-release digest stays directly
comparable to the npm published shasum:

```bash
node scripts/socket-release/github-release.mts --tag vX.Y.Z --release
```

Never hand-run `gh release create` without `--draft`: the release goes
immutable the instant it publishes, so assets and checksums must be attached
while drafted.

## Healing a release gap

A RELEASE GAP is a version public on its registry with the `v<version>` tag
or GitHub release missing. Re-running `--approve` does NOT heal it (the
approve leg drops already-published versions before the tag step). The
healer is:

```bash
node scripts/socket-release/github-release.mts --tag vX.Y.Z             # dry-run: confirms liveness
node scripts/socket-release/github-release.mts --tag vX.Y.Z --release   # cuts tag + release
```

It refuses (exit 1) when the version is not live - an unreachable registry
is never read as unpublished. From CI, the operator dispatches the
`github release` workflow with `tag` + `release: true` from the Actions UI
(`gh workflow run` is guard-blocked for agents - the human clicks; there is
no agent lane for the dispatch itself).

## Verifying

- The tag exists on origin: `git ls-remote --tags origin refs/tags/vX.Y.Z`
- The release exists and is not a draft:
  `gh release view vX.Y.Z --json isDraft,assets`
- `checksums.txt` is attached when any binary assets are (the brew channel
  hard-requires it).