Skip to content

Pixel-CLI/pixel / .agents/skills/release

release

Verified

Cut a pixel release end to end — pick the version, prepare the release commit (changelog cut, lockstep version bump, Cargo.lock, check-release) with prepare.sh in a pull request into main, tag vX.Y.Z on its merge to trigger .github/workflows/release.yml, and verify the published release, the install.sh asset and the Homebrew tap with evidence. Also covers resuming an interrupted release, patch releases while main is not releasable, and recovering from a failed Release run. Use when asked to release, publish, tag or ship a new pixel version, bump the version, cut the changelog, check a published release, or when the Release workflow failed.

Releasing pixel

main is the only long-lived branch: pull requests merge into it by default, and a release is a tag on it. The one exception is a patch that cannot wait for main to be releasable: the fix still merges into main, then a maintenance-release pull request targets a release/x.y branch cut from the line's last tag (see "Patch release while main is not releasable").

The tag is the release. Pushing vX.Y.Z runs .github/workflows/release.yml, and its verify job gates publication; ordinary CI does not run on tags. The dependency graph is verify → fuzz → assets → release, then smoke and virustotal independently:

JobDoesA failure means
verifycheck-release $GITHUB_REF (CLI version, every workspace member in Cargo.lock, released heading and empty Unreleased), cargo deny check, then locked workspace testsnothing built or published
fuzzfuzz.yml called with 120 s per target: every cargo-fuzz target on nightly, cargo deny on fuzz/ firsta crash or a target that ran nothing: nothing built; the reproducer is the run's fuzz-artifacts-* artifact
assetscalls release-build.yml: three target builds (musl x86_64/aarch64 with model2vec only, native Apple arm64), checksums and feature-specific CycloneDX SBOMs; attest makes formulas and Linux bottles, signs archives/bottles/install.sh/SBOMs, stages the provenance bundlenothing published
releasepublishes the staged assets with the tag's changelog section, then updates LivioGama/homebrew-tap using HOMEBREW_TAP_TOKENpublication may already be immutable; classify in Recovery
smoke (×3, fail-fast: false)verifies provenance, runs the downloaded asset and one-liner in an empty HOME; checks macOS tap install/test and Linux bottle pouring when available; version and commit must match the tagalready published; distinguish code failure from infrastructure
virustotalsubmits the three archives and appends report links to the notes when VT_API_KEY existsalready published; missing key is a notice, not a scan pass

Three facts shape everything below:

  • The macOS binary is first run by smoke. cross-build.yml builds all three release targets on every push to main with release-build.yml's exact commands, so a green main proves each lane compiles and links; nothing before smoke runs the darwin binary. The same job saves the per-target cache (release-<target>) that the tag's assets / build job restores, and the verify job restores ci.yml's linux-debug one: a tag run reads the default branch's caches, never another tag's.
  • A published release is immutable. GitHub's release immutability is on: once release has published, its assets cannot be added, replaced or deleted, and its tag cannot move or be deleted while the release exists (a deleted release's tag name cannot be reused). The release tags: immutable ruleset also refuses deleting or moving any v* tag, with a bypass for the Admin role only. An asset fix ships as the next patch. Title and notes remain editable: an editorial correction goes through a changelog PR, then gh release edit --notes-file <complete-corrected-body>, preserving VirusTotal links and noting the correction after publication. Re-read and diff the live body immediately before editing so concurrent additions are preserved. It needs no new tag; never rebuild an asset for a notes fix.
  • Users install releases, not main. install.sh is a release asset (releases/latest/download/install.sh), so main may be ahead of the latest release, broken script included, without breaking an install.

Authority

Being asked to fix, merge or ship a change is not an authorization to release. A release starts on the user's explicit ask ("release", "/release", "cut 0.5.0"), and that ask is the go for the whole happy path: pick the version, prepare, open the PR, merge it once green, tag its merge commit once that commit's push CI is green, watch the run and verify the publication. Run it to the end without pausing for confirmation; say each outward command (merge, tag push) in a progress line just before running it, and report once, with the step 5 summary. An ask that limits the scope ("prepare 0.5.0", "don't tag yet") stops there.

Stop and ask only when something is off — the happy path's evidence is missing or contradicts itself:

  • a precondition fails: dirty tree, red CI/Cross-build on origin/main's head, the last tag not on main, nothing to release, less disk than the gates need after deleting target/debug/incremental (itself routine);
  • the version is not clear-cut: a fragment that could read either as patch or as minor, anything that would make it 1.0.0 or a major, or a user who named a version the convention contradicts;
  • prepare.sh or check-release refuses, the diff holds anything beyond the list in step 3, or a user-visible pull request has no entry you can write from its body alone;
  • a gate is red and the failure is not provably local (reproduce it with the suspected variable or config unset);
  • a PR check is red or cancelled, or a review left an actionable comment;
  • the merge commit is not on main, is not the prepare PR's, or its push CI is red;
  • any failed Release run: classify it (Recovery), and ask before anything beyond one gh run rerun --failed for an infra failure.

Whatever the path, these always wait for their own go, even inside a release the user asked for: deleting or moving a tag (an Admin bypass of the tag ruleset), force-pushing, retagging, editing the tap by hand, and deleting a release or its assets.

Identify the PR author, eligible reviewer and merge operator before preparation. GitHub review requirements and the client's execution permissions remain in force. If a client refuses an unreviewed/admin merge, record the block, prepare the exact SHA, checks and merge command for the maintainer, and resume when the merge is observed; do not retry the same bypass. Prefer an eligible maintainer's review to weakening protection.

For an advisory, read Private advisory release before promising patched_versions or importing the fix. It owns private validation, exceptional merge handling and the disclosure order.

Commands use the current names (new-branch, repo-state, commit). A pixel that rejects them predates 0.2.5: update it before releasing.

The release record

A release spans a workflow run, a PR and possibly a context reset. Keep its state in release-x.y.z.md in the session scratchpad, written at the start and updated after every step, so a resumed session reads it instead of reconstructing the release from gh output:

# pixel x.y.z
- version / reason: x.y.z, patch|minor because …
- candidate: target branch / base SHA / validated prepare head SHA / merge SHA
- coverage: last shipped tag / candidate SHA / PRs and direct commits accounted for
- validation: SHA / exact command / log or run URL / exit status
- prepare PR: #NNN (merged <merge sha> | open); author / reviewer / merge operator
- equivalence: merge parent == base; merge tree == prepare tree
- tag: vx.y.z → <sha> (pushed | not yet)
- release run: <run-id> <url>; verify ✓/✗, assets ✓/✗, release ✓/✗, smoke ✓/✗, virustotal ✓/notice/✗
- publication: assets ✓/✗, install.sh ✓/✗, body ✓/✗, tap ✓/✗, binary ✓/✗
- advisory: GHSA / validated private and imported patch SHAs / patched version / published_at
- exceptions: check / reason / maintainer decision / protection restoration evidence
- follow-ups: PR / open|merged|closed / owner / closure condition
- failure: <job, step, class (code|tooling|infra), evidence>
- next action: <one command, and whether it waits for the user (Authority)>

On resume, trust the record only as a map: re-read the live state it points at (gh pr view, gh run view, git ls-remote origin refs/tags/vx.y.z) before acting, and replace stale fields rather than appending contradictory status blocks. Keep exactly one current next action.

1. Preconditions

unset GIT_DIR GIT_WORK_TREE GIT_COMMON_DIR GIT_INDEX_FILE GIT_OBJECT_DIRECTORY \
    GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_PREFIX
git fetch origin --tags
pixel repo-state                                   # clean tree
LAST=$(git tag --list 'v[0-9]*' --sort=-v:refname | head -n 1)
gh run list --branch main --workflow ci.yml --status completed -L 1           # success
gh run list --branch main --workflow cross-build.yml --status completed -L 1  # success
git merge-base --is-ancestor "$LAST" origin/main && echo "$LAST is on main"
git log --oneline "$LAST"..origin/main | head      # something to release
gh secret list | grep HOMEBREW_TAP_TOKEN
  • Pick the last tag by version sort, not git describe: v0.2.4's commit is not an ancestor of main (it was replayed before the histories were joined), so describe can answer an older tag.
  • Read the last completed run of each workflow, not main's head: a run still in progress there (a website merge, say) does not hold the prepare, since step 4 waits for the prepare commit's own push run before tagging.
  • A red Cross-build on main means a release lane fails with --locked: the assets job will fail the same way. A red Dependency policy (cargo-deny) blocks every PR, the prepare PR included: a fresh RustSec advisory is a chore(deps) PR (cargo update -p <crate>) merged before step 3.
  • The local gates need room: a workspace build plus target/debug/incremental can fill the disk mid-gates (No space left on device from cargo nextest). Check df -h . first; target/debug, target/dev-release and target/release are rebuildable, and CARGO_INCREMENTAL=0 keeps a one-off gate run from growing the cache.
  • Without HOMEBREW_TAP_TOKEN the tap is not updated (a warning, not a failure).
  • main holds work that must not ship yet? Stop and read "Patch release while main is not releasable" below.

2. Pick the version

Read .github/changelog.d/ in the repository root and the last tag. Pre-1.0 convention in this repo:

  • patch (0.2.4 → 0.2.5): fixes, additions, renames that keep the old spelling as an alias. 0.2.x patches have shipped Added sections.
  • minor (0.2.x → 0.3.0): something a user of the previous minor must act on — a removed command or flag with no alias, a changed JSON output or protocol field, a changed on-disk format under .pixel/, an install layout that pixel setup does not migrate.

Pick the version by that convention, state it with its one-line reason in a progress line, and go on; stop only on the cases Authority lists. Check that what a Removed or Changed fragment breaks actually shipped in the last tag (git cat-file -e v<last>:<path>, or git grep the command at the tag): 0.5.0 carried a Removed entry for pixel classify backends that no release had ever held, so it was no reason for a minor and no entry at all. Start the record.

Then write .github/changelog.d/_highlights.md on the release branch, unless the release is a handful of unrelated fixes: a lead paragraph saying what this release is about, then a ### Highlights list of two or three bullets. It becomes the top of the released section and of the GitHub release body, which is what keeps that narrative out of the individual entries (### and below only, 2000 bytes; prepare.sh refuses more).

3. Prepare the release commit

Set TARGET=main for a regular release or TARGET=release/x.y for a maintenance release, and prepare from origin/$TARGET on release-x.y.z. Record the full BASE=$(git rev-parse "origin/$TARGET") before preparation and PREPARE_HEAD=$(git rev-parse HEAD) after its final validated commit. A rebase invalidates that record and its changelog coverage, even if Git reports no conflict: review every newly included PR and direct commit, fold new fragments into the released section, then validate and record anew.

unset GIT_DIR GIT_WORK_TREE GIT_COMMON_DIR GIT_INDEX_FILE GIT_OBJECT_DIRECTORY \
    GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_PREFIX
git fetch origin "refs/heads/$TARGET:refs/remotes/origin/$TARGET"
BASE=$(git rev-parse "origin/$TARGET")

Prepare:

pixel new-branch release-x.y.z --from "origin/$TARGET" --request-id "release-x.y.z-branch"
.agents/skills/release/prepare.sh x.y.z        # --date YYYY-MM-DD to override today

prepare.sh refuses before writing when the tag or the ## [x.y.z] heading already exists, .github/changelog.d/ holds no fragment, or ## [Unreleased] still carries a bullet of its own. It also refuses before writing when scripts/ci/check-claims.py --version x.y.z fails, naming each claim in docs/bench/claims.toml the new version would leave more than one minor behind with no tracking issue: the prepare PR may not edit the registry and skips the CI job that checks it, so a stale claim would only turn the merge commit red (0.10.0, #1359). Re-measure it (scripts/bench/refresh-claim.sh <id>) or add tracking = "#<issue>" to its entry through a pull request into $TARGET, merge that, then prepare from the new base. Otherwise it:

  1. sets [package] version to x.y.z in every workspace member (lockstep, as 0.2.4 did);
  2. folds the fragments into a new ## [x.y.z] - DATE under a kept, now empty ## [Unreleased], led by _highlights.md when there is one and then grouped by section in the order the headings have always used, and deletes them all; an entry that names no pull request (no /pull/<n> in the text, no number opening the slug) gets ([#<n>](…)) appended from the first-parent commit that added it ((#<n>) or Merge pull request #<n>), and one whose commit names none refuses the cut before any write: name the pull request in that fragment's text, then re-run. A security entry may instead link this repository's GHSA (including a draft); an advisory import has no public PR number;
  3. runs cargo update --workspace so Cargo.lock follows;
  4. lists the pull requests merged into main since the last tag that the candidate contains, then its commits in no merged pull request. The inventory is collected before any writes, using GitHub's canonical repo name (an old transferred remote may search empty). A failed, capped or contradictory lookup refuses the cut; repair it before rerunning;
  5. runs cargo run -q -p pixel-cli -- check-release vx.y.z --repo ., the verify job's command, from the tree. It uses the tree's CLI on purpose: an installed 0.2.4 binary only knows the old release-check name.

It must end with release-check: all checks passed. Then:

  • Changelog completeness. Every feat, fix and perf pull request merged since the last tag, and any other with a user-visible effect, needs an entry (CONTRIBUTING.md exempts pure refactors and CI/deps chores). The run lists the fragments it released above the pull requests, and a fragment named after its pull request matches one line to one, so an entry nobody wrote shows as a pull request with no fragment. Write the missing one straight into the new ## [x.y.z] section, in the same commit: re-running prepare.sh would refuse the heading it has already written. The commits listed as belonging to no pull request are the ones nobody filed an entry for: each user-visible one needs an entry too. Check whether a feature already shipped with git cat-file -e v<last>:<path> before calling it new.
  • Release body. Read the new ## [x.y.z] section as a stranger: it is published verbatim. Fix wording or section order now, not after the tag.
  • Threat model. Read the same section against docs/threat-model.md section 4: an entry that adds an entry point, a sidecar file, a network destination, a secret, a hook or an install target that the threat model does not name gets a docs pull request into main before the tag, not an edit here (the scope rule below refuses it).
  • Diff. prepare.sh ends with scripts/release/release-prepare-only.py HEAD, the rule CI's scope job applies: only version lines (all member Cargo.toml, Cargo.lock), CHANGELOG.md and deleted .github/changelog.d/*.md fragments. A refusal names each offending file: it is a bug in the release branch, not something to push.
  • Gates. GIT_CONFIG_GLOBAL=/dev/null scripts/ci/gates.sh --force (fmt, clippy, tests). Without GIT_CONFIG_GLOBAL, a developer's global git config fails tests that CI passes (blame.ignoreRevsFile, rerere/mergiraf in the provenance and reconcile tests); a red gate that CI does not reproduce must be explained, with a passing isolated rerun for the recorded SHA. Fixtures set their identity locally; keep the global isolation. The verify job reruns tests, but failure there leaves a pushed tag requiring an explicit recovery decision.

A log wrapper must return the gate's status even after printing its tail:

rc=0
GIT_CONFIG_GLOBAL=/dev/null scripts/ci/gates.sh --force >"$log" 2>&1 || rc=$?
tail -30 "$log"
exit "$rc"

Run that as its own background command, preserving the SHA, log and exit status in the record; it must not swallow a failing gate behind tail.

pixel commit -m "release: prepare x.y.z" --request-id "release-x.y.z-prepare"
git push -u origin release-x.y.z
gh pr create --base "$TARGET" --title "release: prepare x.y.z" --body-file <body>

Body: the version, the reason for patch/minor, the gate output, "tag vx.y.z follows on this PR's merge commit".

Watch checks in the background with gh pr checks <n> --watch --interval 30 after confirming checks exist. A watcher can finish before another workflow reports: its exit alone does not attest completeness. Before merging, inspect the current PR head SHA, every applicable workflow and reviews; before tagging, inspect the exact merge SHA's push CI and Cross-build runs. An absent required run is missing evidence, never a successful skip. Avoid foreground sleep loops.

A healthy prepare PR shows four scope / Release-prepare scope checks passing (one per workflow: CI, Mutants, Cross-build, Homebrew core) and every other CI job skipping (Test + Format, Lint, MSRV, Ranking gates, cargo-deny, Mutants plan and gate, Cross-build, brew install --build-from-source); CodeRabbit skips on the title (ignore_title_keywords). The diff holds no code, and step 3's local gates plus the push run on its merge commit, which step 4 waits for, cover it. If Test + Format or Mutants runs, scope refused the diff: stop and read its log, do not wait for green. A maintenance release into release/x.y keeps every job, and there green is the bar. Homebrew skips the source audit for a normal prepare PR, whose tag URL cannot exist before merge. Weekly or later PR checks still audit released source formulas; the skip is not a claim that the future tag URL was audited.

Immediately before merging, fetch the target and run the candidate guard with the recorded SHAs and the selected target. For maintenance, append --maintenance to both guard calls; that mode permits the tested backport code but keeps the ancestry, fragment and tree checks:

unset GIT_DIR GIT_WORK_TREE GIT_COMMON_DIR GIT_INDEX_FILE GIT_OBJECT_DIRECTORY \
    GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_PREFIX
git fetch origin "refs/heads/$TARGET:refs/remotes/origin/$TARGET"
python3 .agents/skills/release/check-candidate.py "$BASE" "$PREPARE_HEAD" --tip "origin/$TARGET"

If the base moved or GitHub reports BEHIND, refresh coverage and validation; never bypass the stale candidate. The guard after merge closes the remaining race between this fetch and GitHub merging. All skipped but scope, or all green on release/x.y, and no actionable review comment: merge it, squash like every PR on main (gh pr merge <n> --squash --delete-branch).

4. Tag

Tag the prepare PR's merge commit, not whatever main's head is by then: another PR merged in between would ship unreviewed in the release. Wait for that commit's push CI (CI, Cross-build) to be green on main. The current push workflows select main only: for maintenance, require the complete prepare PR CI/Cross-build verdict for PREPARE_HEAD and the exact-tree guard below instead of waiting for nonexistent maintenance push runs.

unset GIT_DIR GIT_WORK_TREE GIT_COMMON_DIR GIT_INDEX_FILE GIT_OBJECT_DIRECTORY \
    GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_PREFIX
git fetch origin "refs/heads/$TARGET:refs/remotes/origin/$TARGET"
SHA=$(gh pr view <n> --json mergeCommit --jq .mergeCommit.oid)
python3 .agents/skills/release/check-candidate.py "$BASE" "$PREPARE_HEAD" --tip "origin/$TARGET" --merge "$SHA"
git show --stat "$SHA" | head -5                      # the merge of release: prepare x.y.z
git show "${SHA}:crates/pixel/Cargo.toml" | sed -n 3p # version = "x.y.z"; braces: zsh reads "$SHA:c" as a modifier
gh run list --branch "$TARGET" --commit "$SHA"             # CI and Cross-build: success
git tag -a vx.y.z -m "pixel x.y.z" "$SHA"             # annotated, as v0.2.4
git push origin vx.y.z                                # the release ask covers it (Authority)

A failed candidate guard means no tag: prepare a new reviewed candidate with complete coverage and gates. Tree equality alone is insufficient; the guard checks the merge parent too. Record the SHA, then find the run and watch it in the background, never with a foreground sleep loop:

gh run list --workflow release.yml -L 1               # the run for vx.y.z
gh run watch <run-id> --exit-status                   # run_in_background: true

Pass run ids literally. Under zsh (Claude Code's command tool) an unquoted $var is not split into words: set -- $ids or for x in $list over a space-separated string sees one word, and a watcher built that way reports failures that never happened.

About 12 minutes to the end of smoke (0.3.0: verify 5 min, builds 6 min, publish and smoke under a minute; 0.5.0, uncached: builds 5.3 to 5.5 min on musl). The fuzz job, added after 0.7.0, sits between verify and the builds: about 5 more minutes (nightly build of the targets, then 120 s per target).

5. Verify the publication

Start from the smoke jobs: gh run view <run-id> --repo Pixel-CLI/pixel must show all three green, and each job log names what it installed and the --version it read. Skipped steps inside build and smoke are the other target's lane (each matrix entry skips the cross or native build it does not use), not a caveat. A step that printed a ::notice:: (install.sh on a tag that is not the latest) or was skipped (Homebrew without the token) is a caveat to report, not a pass.

smoke does not see the release body or the formula hashes against the tap. Check those from the published state, never the local checkout, downloading into a fresh directory so nothing local vouches for the release. The binary lines repeat smoke by hand: run them when a smoke job failed, was skipped, or predates the job (0.2.4 and older):

V=vx.y.z; D=$(mktemp -d); cd "$D"
gh release view $V --repo Pixel-CLI/pixel --json isDraft,isPrerelease,isImmutable,body \
  --jq '{isDraft, isPrerelease, isImmutable, body: .body[0:200]}'   # false, false, true, the changelog section (not "See [CHANGELOG.md]")
gh release download $V --repo Pixel-CLI/pixel
ls                                                     # 15 assets: 3 archives, 3 checksums, 3 SBOMs, 2 bottles, 2 formulas, installer, bundle
for f in pixel-v*.tar.gz pixel-v*.cdx.json pixel-*.bottle.tar.gz install.sh; do
  gh attestation verify "$f" --repo Pixel-CLI/pixel --signer-workflow Pixel-CLI/pixel/.github/workflows/release-build.yml || exit "$?"
  gh attestation verify "$f" --repo Pixel-CLI/pixel --signer-workflow Pixel-CLI/pixel/.github/workflows/release-build.yml --bundle "pixel-$V.intoto.jsonl" || exit "$?"
done
shasum -a 256 -c ./*.sha256                            # 3 × OK
for f in ./*.sha256; do grep -c "$(awk '{print $1}' "$f")" pixel.rb; done   # darwin 2, each musl 1: the formula carries the real hashes (darwin is also the formula's top-level url)
for b in ./*.bottle.tar.gz; do grep -c "$(shasum -a 256 "$b" | awk '{print $1}')" pixel.rb; done   # 1 each: the bottle block names the published bottles
curl -fsSL "https://github.com/Pixel-CLI/pixel/archive/refs/tags/$V.tar.gz" | shasum -a 256 | awk '{print $1}' | xargs -I{} grep -c {} pixel-core.rb   # 1: the core formula names the tag's source archive
git -C <repo> show "${V}:scripts/release/install.sh" | diff - install.sh && echo "install.sh == tag's"
gh api repos/LivioGama/homebrew-tap/contents/Formula/pixel.rb --jq .content \
  | base64 -d | diff - pixel.rb && echo "tap == release formula"
tar xzf pixel-$V-aarch64-apple-darwin.tar.gz
HOME="$D/home" ./pixel-$V-aarch64-apple-darwin/bin/pixel --version
git -C <repo> rev-list -n 1 $V                         # must equal the `commit:` line above
gh run view <run-id> --repo Pixel-CLI/pixel         # no ANNOTATIONS section = no no-token/no-changelog warning

Verify the asset names, not only the count: release-build.yml stages 15 files (3 archives + 3 checksums + 3 SBOMs + 2 bottles + 2 formulas + installer

  • provenance bundle). Read each SBOM's metadata against its target and version; a bundle file alone is not a successful provenance verification. Read the full published body against the released changelog section, allowing the workflow's VirusTotal addition and recorded editorial corrections. Check the VirusTotal job separately from smoke and report an absent key as unscanned.

pixel --version prints pixel x.y.z and commit: <sha>: the commit line proves the binary was built from the tag, which the version number alone does not. The run in an empty HOME proves it starts without this machine's config. Read warnings from the run summary's annotations, not from --log | grep '::warning::': the log echoes each step's script, so that grep matches the workflow's own echo "::warning::…" line on every run. The Linux tarballs cannot run here; their hashes and the formula are the evidence for them.

Report in this shape, and copy it into the record:

Release vx.y.z: published and verified | NOT verified
- run <url>: verify ✓, assets (builds + attest) ✓, release ✓, smoke ✓✓✓, virustotal ✓ | notice
- smoke: asset ✓✓✓, install.sh ✓✓✓ | notice, brew macOS ✓ | skipped, brew Linux bottle ✓✓ | notice
- assets: 15, 3 SBOMs, provenance online + bundle verified with release-build.yml, 3 checksums OK, formula, bottle and source-archive hashes match, install.sh == tag's, immutable
- body: CHANGELOG ## [x.y.z] section + VirusTotal links when enabled + recorded corrections
- tap: Formula/pixel.rb == release pixel.rb (commit "pixel x.y.z")
- binary: aarch64-apple-darwin prints pixel x.y.z, commit <sha> == tag
Caveats: <anything not checked, and why>

Recovery

Classify the failure before touching anything, from the failed step's log (gh run view <run-id> --log-failed), and write it into the record:

ClassLooks likeRetry?
infrarunner lost, network or registry timeout, GitHub 5xx, rate limitgh run rerun <run-id> --failed once; a second identical failure is not infra
toolingan action or cross image broke, an expired HOMEBREW_TAP_TOKEN, a toolchain changea rerun cannot help: it replays the workflow file and commit of the tag. Fix on main, then re-tag (unpublished) or next patch (published)
codecheck-release or a test fails, a target does not compile or linkfix on main through a PR, then re-tag (unpublished) or next patch (published)

Then by how far the run got:

Where it failedStateDo
verify, fuzz or assetstag pushed, nothing publishedwith the user's go, delete the tag (git push origin :refs/tags/vx.y.z && git tag -d vx.y.z; the tag ruleset lets only an Admin do it) and re-tag the fixed commit. No release exists, so reusing the version is safe. A musl failure should have shown on main's Cross-build: find out why it was green.
release, before or during "Upload release assets"nothing published (the action uploads into a draft and publishes last; a leftover draft is reused by a rerun)as above, or a rerun for infra
release, tap steps onlyGitHub release published and immutable, tap staledo not rerun the job: it replays "Upload release assets", which an immutable release refuses. Copy the pixel.rb release asset into Formula/pixel.rb of LivioGama/homebrew-tap by hand, commit pixel x.y.z.
smoke, install.sh onlybinaries fine, the published script is brokenthe script ships with the release and cannot be replaced: fix it on main through a PR and release the next patch
smoke, asset or brew, infraunknowngh run rerun <run-id> --failed reruns only the failed smoke jobs
smoke, asset or brew, code (wrong version or commit, crash, brew test fails) — or any later report of a bad binaryusers may have itnever move the tag: fix on main, release x.y.z+1, say in its changelog what was wrong with x.y.z.

Patch release while main is not releasable

An urgent fix normally needs nothing special: merge it into main and cut the next patch with steps 1 to 5. Only when main holds work that must not ship yet:

  1. Merge the fix into main first, as any PR.
  2. Record the target base SHA before cherry-picking; the final prepare head includes both the backport and release metadata. Use --maintenance in both candidate guards, and require full CI instead of a prepare-only skip. Push release/x.y from vx.y.<last> if the line has none yet (git push origin vx.y.<last>^{commit}:refs/heads/release/x.y). On a release-x.y.z branch from origin/release/x.y, git cherry-pick -x <fix merge sha> (-m 1 for a merge commit), add its .github/changelog.d/<slug>.<section>.md fragment, then prepare.sh x.y.z and the gates as in step 3; PR into release/x.y.
  3. Tag that PR's merge commit (step 4) and verify (step 5). smoke notices install.sh as not checked when a newer line is already the latest release.
  4. On main, a follow-up PR adds the ## [x.y.z] - DATE section with that entry, so the changelog on main records every release.
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 196kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 196kUpdated Claude CodeCodexVerifiedInstall