release
Skill115 starsChanged 5 days agoApache-2.0View on GitHub
Run a Mokka (NVIDIA/k8s-test-infra) release end to end. Covers the release-prep PR (changelog fold), merge, signed tag, publish pipeline checks, `make verify-release`, the GitHub release notes, the stacked chart bump to the next -dev version, and the Slack announcement draft. Use this whenever the user wants to cut, prepare, tag, publish, verify or announce a Mokka release, says "release 0.7.0", "prepare v0.7.0", "fold the changelog for the release", "push the tag", "create the GitHub release", "bump the charts after the release" or "draft the release announcement", or picks up a release that is already partway done. Also use it for an out-of-cycle patch release (vX.Y.Z) and for a security release that fixes a CVE, GHSA or Go vulnerability ("cut a security release", "ship the fix for GHSA-…").
- Commits and pushes
193 other projects use a version of this.
Adopted by
Most recently taken up by
- CoreBunch/Instatictheir own version, first seen Nov 16, 2026
- coredevices/PebbleOStheir own version, first seen Nov 16, 2026
- yicheng47/runnertheir own version, first seen Nov 13, 2026
- eugene1g/agent-safehousetheir own version, first seen Nov 12, 2026
- BlockRunAI/ClawRoutertheir own version, first seen Nov 11, 2026
- cubeplexai/cubeplextheir own version, first seen Nov 10, 2026
Used with
Projects with it also use create-agent-adapter, changelog-style and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
MicrosoftSkillcreate-agent-adapter
Technical guide for creating a new Paperclip agent adapter. Use when building a new adapter package, adding support for a new AI coding tool (e.g. a new CLI agent, API-based agent, or custom process), or when modifying the adapter system. Covers the required interfaces, module structure, registration points, and conventions derived from the existing claude-local and codex-local adapters.
Also in 5 projects that use this
GrinvSkillchangelog-style
Turn a commit range into CHANGELOG.md entries following common-changelog style. Use when finishing a PR or cutting a release, to write/fix the [Unreleased] section's entries — moving [Unreleased] under a new dated version heading is a separate, automated step (see the release skill / scripts/sync-version.ts), not this skill's job.
Also in 4 projects that use this
GrinvSkilldocs-consistency-check
Check README/manifest.json/server.json/CHANGELOG.md/AGENTS.md and docs/*.md for drift against the actual registered tools and source. Use after adding, renaming, or removing a tool, or as part of a live-audit pass.
Also in 4 projects that use this
Microsoft AzureSkillcomponent-release
Prepares a verifiable Agent Landing Zone UI release. Use for release branches, VERSION, changelog entries, tags, release notes, and compatibility evidence; never publish without explicit human approval.
Also in 4 projects that use this
Microsoft AzureSkilldocumentation-consistency
Keeps AI Landing Zone contributor, user, and operator documentation aligned with shipped Bicep behavior. Use for parameters, defaults, outputs, topology, deployment flow, operations, or releases.
Also in 8 projects that use this
rivet-devSkilllaunch-graphics
Generate agentOS marketing/launch graphics (launch & social heroes, code-snippet cards) from the committed generators in docs-internal/graphics. Use when asked to make, update, or render an agentOS launch image, social image, "agentOS Apps" graphic, or technical code-snippet image.
Also in 3 projects that use this
- +3 more from Grinv
Other versions193 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 193
- paperclipai/paperclip★ 114ksame name
- modelcontextprotocol/servers★ 92ksame name
- remotion-dev/remotion★ 73ksame name
- traefik/traefik★ 66ksame name
- usememos/memos★ 64ksame name
- tw93/Pake★ 64ksame name
- AmruthPillai/Reactive-Resume★ 46ksame name
- amruthpillai/reactive-resume★ 46ksame name
- reactive-resume/reactive-resume★ 46ksame name
- Yeachan-Heo/oh-my-claudecode★ 41ksame name
183 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
The file
Show its rules and text
We split this skill into the rules it gives an agent
22 rules. 0 are common, 5 are distinctive, and 17 are very specific to this project.
0
Common
Most of the 183 edited versions we read keep these.
5
Distinctive
This author's own choices. Worth a look.
17
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 31
Sign everything: Use git commit -s -S, git rebase --signoff -S and git tag -s.
- Very specific: line 39
Write version numbers without the v for images, charts, CHANGELOG headings and make targets (0.7.0).
- Very specific: line 64
If the go directive in go.mod rose since the last tag, the notes state the new minimum Go version.
- Very specific: line 79
Check that every released version has its section in main's CHANGELOG.md: git show vA.B.C:CHANGELOG.md against main.
- Distinctive: line 94
Remove fragments that describe states no release shipped, such as fixes to a feature that is new in this release.
- Very specific: line 97
Every breaking change starts with Breaking: and states the user's action.
- Very specific: line 99
Every Removed entry needs a deprecation announced three Y releases earlier.
- Very specific: line 102
Check a fix against the previous tag (git grep … vA.B.C -- …) before deciding that it fixes something released.
- Distinctive: line 104
Commit these edits with a body that lists each removal and the reason.
- Very specific: line 105
Fold: run make changelog-preview RELEASE_VERSION=X.Y.Z, then make changelog-release RELEASE_VERSION=X.Y.Z.
- Very specific: line 110
Charts: leave Chart.yaml unchanged, at X.Y.0-dev.
- Very specific: line 117
Gates: run make helm-tests, make helm-crds-tests, make lint, make build and make test.
- Very specific: line 136
Run make helm-tests, make helm-crds-tests and go test ./tests/hack/....
- Very specific: line 152
Write the PR bodies with .github/pull_request_template.md.
- Distinctive: line 159
Merge the prep PR: only with approval and green checks, after the user confirms.
- Very specific: line 168
CI must be green on the prep merge commit: before tagging: gh run list --workflow "CI Pipeline" --commit <merge-sha>.
- Very specific: line 185
Never push an -rc or other non-stable tag.
- Very specific: line 203
If a publish run failed, read its log (gh run view <id> --log-failed) before acting.
- Distinctive: line 209
Late fragments first: If Phase 3 listed fragments, follow the template's "After the release" item before writing any notes: a PR against …
- Very specific: line 227
Run it from a checkout of the merged main, because it reads the release's section from CHANGELOG.md.
- Very specific: line 242
If the user wants the release out before the publish runs finish, create it with the digests that are final, mark the rest as pending, and …
- Very specific: line 250
Update the tracking issue with the tag, the release link, the verify-release output and the changelog section, then close it.
“Common” is measured: kept by at least 6 in 10 of the 183 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Mokka release
A release takes main to published, signed images and charts plus a GitHub
release. Every release is cut from main, security releases included:
docs/support-policy.md allows no release branches and no backports, so a
fix ships from main and users upgrade to it. The repository's own checklists
are the source of truth:
.github/ISSUE_TEMPLATE/release.yml (scheduled vX.Y.0) and
.github/ISSUE_TEMPLATE/patch_release.yml (out-of-cycle). Read the one that
applies at the start, because it can change between releases and wins over this
skill. This skill adds the order of operations, the commands, and the lessons
from earlier releases (see references/gotchas.md).
Ground rules
- Find out where the release stands first. A release spans hours and often
more than one session. Before doing anything, check: does a
vX.Y.Ztag exist (git ls-remote --tags upstream)? Is there a GitHub release (gh release view)? Is there an open or merged prep PR? Is there a tracking issue? Then resume at the first unfinished phase. - Confirm each outward step. Merging, pushing a tag, creating the GitHub release and closing PRs are visible to everyone, and a pushed tag starts publishing artefacts that cannot be unpublished. Get a yes for each one, even when the user asked for the whole release. A yes for one step does not cover the next.
- Sign everything. Use
git commit -s -S,git rebase --signoff -Sandgit tag -s. If signing fails, stop and report it. Never fall back to unsigned. - Remotes.
upstreamisNVIDIA/k8s-test-infraandoriginis the user's fork. The localmainis usually stale, so always base work onupstream/mainaftergit fetch upstream --tags. - Use a dedicated worktree for the release branch, so the user's other checkouts are untouched.
- Write version numbers without the
vfor images, charts, CHANGELOG headings andmaketargets (0.7.0). Use thevonly for git tags (v0.7.0).
Security releases
A security release is an out-of-cycle release whose reason is "Security". It
runs the same phases with patch_release.yml, plus:
- Cut it from
main, not from the previous tag. The fix merges tomainfirst. Ifmainalso carries non-fix changes since the last tag, the version check makes it the next Y, and the release notes say it shipped ahead of the schedule. If the user wants to release from an older tag or arelease/X.Ybranch instead, stop: that changes the support policy, and the publish workflows andmake verify-releaseassume a tag onmain's history. - Keep an undisclosed vulnerability private. Advisories that are already
public (a dependency CVE, a
GO-entry) go in the issue, the tag message and the notes, as the template asks. For a vulnerability reported privately (a draft GHSA or psirt@nvidia.com), ask the user what may be public before writing it into any issue, PR, commit, tag message or Slack draft, and publish nothing about it before the advisory goes out. - govulncheck on a checkout of the last tag and of the base commit, with
CI's Go toolchain (
references/gotchas.md, "Local gates on macOS"). The base commit must report none of the listed advisories. If the release spans more than one day, rerun it on the base commit on the day of tagging. Paste every output in the issue. - If the
godirective ingo.modrose since the last tag, the notes state the new minimum Go version. - The prep PR keeps the
Securitychangelog entries. The tag message, the release notes' summary and the Slack draft name each fix and its advisory ID, and tell users to upgrade, since older releases get no fix. - For a Z release, skip Phase 2:
main's charts are already at the next minor's-dev. Confirm it, and merge the last bump PR first if it is still open.
Phase 0: Plan
- Work out the version. A scheduled release bumps Y. For a patch release,
follow the version check in
patch_release.yml: it is the next Z only when every change since the last tag is a fix. - Find the previous release, which is the latest stable tag on any branch.
Check that every released version has its section in
main's CHANGELOG.md:git show vA.B.C:CHANGELOG.mdagainstmain. A patch cut from a release branch may never have been ported (v0.5.1 was not). Port a missing section and its compare link in the prep PR, and delete any fragment that release already shipped, so the new notes don't repeat it. - Record the base commit,
upstream/main. Offer to open the tracking issue from the matching template, but only open it if the user agrees.
Phase 1: Release-prep PR
Branch from upstream/main in a new worktree.
- Review the fragments in
.changes/unreleased/before folding. The notes tell a user of the previous release what changed for them. Apply the rules in AGENTS.md ("Changelog") and the pre-flight checks in the template:- Remove fragments that describe states no release shipped, such as fixes to a feature that is new in this release. Also remove fragments for build-time-only tools, refactors and CI, which users never run.
- Every breaking change starts with
**Breaking:**and states the user's action. - Every
Removedentry needs a deprecation announced three Y releases earlier. Don't silently drop or keep one that fails this: flag it in the PR for the release engineer. - Check a fix against the previous tag (
git grep … vA.B.C -- …) before deciding that it fixes something released. - Commit these edits with a body that lists each removal and the reason.
- Fold: run
make changelog-preview RELEASE_VERSION=X.Y.Z, thenmake changelog-release RELEASE_VERSION=X.Y.Z. Add the compare link[X.Y.Z]: …/compare/vPREV...vX.Y.Zabove the previous one. Count the fragments the fold removed and the bullets in the new section; the two counts must match, and both go in the PR. - Charts: leave
Chart.yamlunchanged, atX.Y.0-dev. The tag sets the publishedversionandappVersion, andmainrefuses to publish a non--devchart version (hack/chart-publish-version.sh). Setting it toX.Y.Zhere breaks every publish run onmainuntil the bump PR lands. - Docs pins:
git grep -nF '<previous-version>' -- docs. Since #1081 the docs don't pin Mokka. Most hits are other projects' versions (DRA driver chart), minimum versions, or "last validated with" records. Leave those. - Gates: run
make helm-tests,make helm-crds-tests,make lint,make buildandmake test. On macOS, readreferences/gotchas.md("Local gates on macOS") before reporting a failure. - Squash into one commit,
chore(release): prepare vX.Y.Z, unless the user wants the steps as separate commits.
Phase 2: Chart bump, stacked on the prep PR
On a branch on top of the prep branch, bump both charts
(deployments/nvml-mock/helm/nvml-mock/Chart.yaml and
deployments/mokka-crds/helm/mokka-crds/Chart.yaml) version and
appVersion to the next minor's -dev (0.8.0-dev after v0.7.0). Also
update the -dev example in docs/helm-chart.md. Commit it as
chore(release): bump the charts to X.Y+1.0-dev.
Mokka has no application version in Go code. The CDIVersion: "0.6.0"
strings in internal/agent/cri and internal/nri are the CDI spec version, so
leave them alone.
Run make helm-tests, make helm-crds-tests and go test ./tests/hack/....
Open both PRs as a GitHub stack with gh-stack. The branches must be in
upstream, because a stack bases each PR on the branch below it:
gh stack init --base main <prep-branch> <bump-branch>
GH_STACK_NO_UPDATE_NOTIFIER=1 gh stack submit --auto --remote upstream </dev/null--auto creates drafts with generated titles. Afterwards, set each PR's title,
body and the skip-changelog label with gh pr edit. gh stack init
attaches any existing PR whose head branch has the same name, fork PRs
included. If that happens, run gh stack unstack --local, rename the branches,
and init again. Later pushes go through gh stack push --remote upstream.
Write the PR bodies with .github/pull_request_template.md. The prep PR's body
covers the fragment corrections with reasons, the fold counts, gate results, and
a "For the release engineer" list of anything that needs a decision. The bump
PR says it merges after the tag.
Phase 3: Merge and tag
- Merge the prep PR only with approval and green checks, after the user
confirms. Don't rebase it just because
mainmoved: every push dismisses approvals, and a PR that is behindmainstill merges. Rebase only when it gets theneeds-rebaselabel (git rebase --signoff -S upstream/main), then rebase the bump branch onto the new prep head, check that every commit is still signed (git cat-file -p <sha> | grep -q '^gpgsig') andgh stack push --remote upstream. Fragments that merged after the fold stay out of the prep PR: step 3 lists them and Phase 5 moves them into the changelog. - CI must be green on the prep merge commit before tagging:
gh run list --workflow "CI Pipeline" --commit <merge-sha>. Watch it withgh run watch <id> --exit-statusin the background. If the user wants to tag before CI finishes, say what that risks and let them decide. - List the fragments that merged after the base commit:
git diff --name-only --diff-filter=A <base> <merge-sha> -- .changes/unreleased. Paste the list in the issue, even when it is empty. Tag the merge commit, given explicitly, with a signed annotated tag. The message has a one-paragraph headline and the breaking changes with their actions:
git tag -s -F <message-file> vX.Y.Z <merge-sha> git cat-file -p vX.Y.Z | head -5 # check: object is <merge-sha>, type commit git push upstream vX.Y.ZNever push an
-rcor other non-stable tag; every publish workflow refuses it. Pushing the tag needs bypass on the tag ruleset.
Phase 4: Check the tag pipeline
Three runs start from the tag: nvml-mock Publish,
Mokka Control Plane Publish and helm-publish
(gh run list --branch vX.Y.Z). Watch them in the background. When all three
succeed, run:
make verify-release RELEASE_VERSION=X.Y.ZIt checks the runs, platforms, X.Y and latest tags, chart versions, every
cosign signature and every SBOM attestation. Every line must be ok:. Keep the
output for the issue.
If a publish run failed, read its log (gh run view <id> --log-failed)
before acting. references/gotchas.md has the known failures. Before rerunning,
check that nobody else already did: gh run view <id> --json attempt,status.
Phase 5: GitHub release
- Late fragments first. If Phase 3 listed fragments, follow the
template's "After the release" item before writing any notes: a PR against
mainmoves each listed fragment's entry into this release's section of CHANGELOG.md, under its kind heading, and deletes the fragment. It also adds a missing**Breaking:**marker and user action. Paste the three counts (folded, listed, bullets in the section) in the PR and applyskip-changelog. Merge it after the user confirms. Skip this step when the list was empty. - Then create the release, once that PR has merged (or right after the tag when the list was empty). Otherwise the notes miss shipped changes, breaking ones included.
Render the notes from the published artefacts:
.claude/skills/release/scripts/release-notes.sh X.Y.Z > <scratch>/notes.mdRun it from a checkout of the merged main, because it reads the release's
section from CHANGELOG.md. Replace the SUMMARY line with two short
paragraphs:
- the headline changes, by component, in plain words;
- "Upgrading:" with the
helm upgradetarget, the number of Breaking: entries to read first, and any default the user should know about, such as a feature gate that is on by default and reaches the internet.
Then:
gh release create vX.Y.Z -R NVIDIA/k8s-test-infra --verify-tag --latest \
--title vX.Y.Z --notes-file <scratch>/notes.mdIf the user wants the release out before the publish runs finish, create it
with the digests that are final, mark the rest as pending, and finish with
gh release edit --notes-file once verify-release passes. Never invent a
digest.
Phase 6: After the release
- Merge the stacked chart bump PR soon after the tag.
- Update the tracking issue with the tag, the release link, the
verify-releaseoutput and the changelog section, then close it.
Phase 7: Slack announcement
Draft the message for the user to paste; don't post it. Use Slack mrkdwn
(*bold*, • bullets, backticks), keep it to about 15 lines, and build it
from the release notes. references/gotchas.md ("Slack template") has the
shape. Link the GitHub release, which exists by now.
Reporting
At each pause, say what is done (with SHAs, PR numbers and URLs), what is running, and the next step that needs the user. When a step was skipped or ran against the checklist (tagging before green CI, for example), say so plainly.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

