docs(release): add a maintainer skill for cutting a release by jd · Pull Request #1795 · Mergifyio/mergify-cli

jd · 2026-09-04T10:04:34Z

RELEASING.md documents the two-stage flow for a human driving the
Actions UI. This adds the agent-facing counterpart: the gh commands
for each stage, the pre-flight checks, and the guardrails.

It lives in .claude/skills/, not the published skills/ tree — that
one ships as the mergify plugin for CLI users, where a runbook for
releasing this repo would fire on anyone asking to release their own
project.

Content beyond what RELEASING.md already covers:

Up front: there is no version to bump in any file, so no "release
prep" PR. The workflow stamps the tag at build time.
Pre-flight: main is green, no leftover draft, what ships since the
last tag.
Stage 2 is irreversible and outward-facing (immutable release, PyPI
push), so the skill stops after the draft and requires an explicit
go-ahead. Stage 1 is marked safe and repeatable.
Post-publish verification of the Homebrew tap, which was undocumented:
the homebrew-tap-sync workflow in Mergifyio/mergify-ci-bot opens a
formula-bump PR against Mergifyio/homebrew-tap within ~20 min of
publish, and it still needs a human to merge.

The why — GitHub's immutable-releases policy and the reason stage 1 runs
from workflow_dispatch — stays in RELEASING.md, which the skill
points at, so the two can't drift on the rationale.

Co-Authored-By: Claude Opus 5 (1M context) noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_01RVKnCd4MKakhVJJiJTfZcD

mergify · 2026-09-04T10:05:23Z

Copilot

🟢 Approval recommended

The change is isolated to documentation for maintainer operations and matches the referenced workflow structure without introducing code risk.

Pull request overview

Adds an agent-facing “releasing” skill runbook under .claude/skills/ that mirrors the existing human-driven RELEASING.md workflow, focusing on driving the two-stage GitHub Actions release process via gh while emphasizing safety guardrails around draft vs publish.

Changes:

Introduces a new maintainer skill document for cutting a release using gh commands (pre-flight checks, stage 1 draft, stage 2 publish).
Documents irreversible vs repeatable steps and enforces an explicit “go-ahead” before publishing.
Adds post-publish verification steps, including the Homebrew tap sync PR flow.

File summaries

File	Description
.claude/skills/releasing/SKILL.md	Adds the agent-oriented release runbook (commands, guardrails, verification, recovery) aligned with the `release.yml` workflow.

Review details

Files reviewed: 1/1 changed files
Comments generated: 0
Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

jd · 2026-09-04T12:59:16Z

This pull request is part of a Mergify stack:

#	Pull Request	Link
1	fix(live-tests): use the admin token for the test-search smoke test	#1796
2	docs(release): add a maintainer skill for cutting a release	#1795	👈

jd · 2026-09-04T12:59:17Z

Revision history

#	Type	Changes	Reason	Date
1	initial	`7805be8`		2026-09-04 12:59 UTC
2	rebase	`7805be8 → 7e8ce16` (rebase only)	Rebased onto the live-tests token fix below it, so this PR's own live-tests run goes green. Diff unchanged.	2026-09-04 12:59 UTC
3	rebase	`7e8ce16 → d1cc0dc` (rebase only)	rebase onto main: the live-tests fix that used to sit under this commit (#1796) is superseded by #1798, which merged on 2026-09-07 and does the same thing plus the doc surfaces. Dropped from the stac…	2026-09-07 12:20 UTC

jd · 2026-09-04T12:59:43Z

Rebased onto #1796, which sits below this one in the stack now. The diff here is unchanged (7805be8 → 7e8ce16, compare — same single file, same content, new parent).

Why: live-tests was red here, and it had nothing to do with this docs-only diff. tests_show_no_match gets a 403 on GET /v1/ci/{owner}/repositories/{repo}/search/tests, on every PR in this repo, since Mergifyio/monorepo#39768 ("cut the ci application key down to least privilege") merged on 2026-09-03 08:40Z — the last green live-tests run was 2026-09-02 13:27Z. That change deliberately dropped search/tests from the ci key's scope, so the test was wrong to use the CI token. #1796 switches it to the admin token; putting it under this PR is what makes this PR's own live-tests run go green.

`RELEASING.md` documents the two-stage flow for a human driving the Actions UI. This adds the agent-facing counterpart: the `gh` commands for each stage, the pre-flight checks, and the guardrails. It lives in `.claude/skills/`, not the published `skills/` tree — that one ships as the `mergify` plugin for CLI users, where a runbook for releasing *this* repo would fire on anyone asking to release their own project. Content beyond what `RELEASING.md` already covers: - Up front: there is no version to bump in any file, so no "release prep" PR. The workflow stamps the tag at build time. - Pre-flight: main is green, no leftover draft, what ships since the last tag. - Stage 2 is irreversible and outward-facing (immutable release, PyPI push), so the skill stops after the draft and requires an explicit go-ahead. Stage 1 is marked safe and repeatable. - Post-publish verification of the Homebrew tap, which was undocumented: the `homebrew-tap-sync` workflow in `Mergifyio/mergify-ci-bot` opens a formula-bump PR against `Mergifyio/homebrew-tap` within ~20 min of publish, and it still needs a human to merge. The why — GitHub's immutable-releases policy and the reason stage 1 runs from `workflow_dispatch` — stays in `RELEASING.md`, which the skill points at, so the two can't drift on the rationale. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RVKnCd4MKakhVJJiJTfZcD Change-Id: I588ca3b86af6143c8440af6cab0b968f80e1a0f7

jd · 2026-09-07T12:21:04Z

Rebased onto main; the diff here is unchanged (7e8ce16 → d1cc0dc, compare).

The live-tests fix that was sitting under this commit as #1796 is superseded by #1798, which merged today and does the same token switch plus the README, --help and mergify-ci skill surfaces it should have carried. #1796 was conflicting with main because of it, so I dropped it from the stack and closed it; this PR now sits directly on main and tests_show_no_match is green upstream.

kozlek

Smart !

mergify · 2026-09-07T13:49:10Z

Copilot AI lite review requested due to automatic review settings September 4, 2026 10:04

mergify Bot had a problem deploying to Mergify Merge Protections September 4, 2026 10:04 Failure

jd had a problem deploying to func-tests-live September 4, 2026 10:04 — with GitHub Actions Failure

Copilot started reviewing on behalf of jd September 4, 2026 10:05 View session

Copilot AI reviewed Sep 4, 2026

View reviewed changes

mergify Bot requested a review from a team September 4, 2026 10:11

jd marked this pull request as ready for review September 4, 2026 12:41

jd force-pushed the devs/jd/worktree-skill/add-maintainer-skill-cutting-release--588ca3b8 branch from 7805be8 to 7e8ce16 Compare September 4, 2026 12:59

jd changed the base branch from main to devs/jd/worktree-skill/use-admin-token-test-search-smoke-test--5a1fe7db September 4, 2026 12:59

jd deployed to func-tests-live September 4, 2026 12:59 — with GitHub Actions Active

jd mentioned this pull request Sep 4, 2026

fix(live-tests): use the admin token for the test-search smoke test #1796

Closed

mergify Bot had a problem deploying to Mergify Merge Protections September 4, 2026 12:59 Failure

jd changed the base branch from devs/jd/worktree-skill/use-admin-token-test-search-smoke-test--5a1fe7db to main September 7, 2026 12:20

jd force-pushed the devs/jd/worktree-skill/add-maintainer-skill-cutting-release--588ca3b8 branch from 7e8ce16 to d1cc0dc Compare September 7, 2026 12:20

jd had a problem deploying to func-tests-live September 7, 2026 12:20 — with GitHub Actions Error

jd deployed to func-tests-live September 7, 2026 12:20 — with GitHub Actions Active

mergify Bot deployed to Mergify Merge Protections September 7, 2026 12:21 Active

kozlek approved these changes Sep 7, 2026

View reviewed changes

mergify Bot requested a review from a team September 7, 2026 13:22

AlexandreGaubert approved these changes Sep 7, 2026

View reviewed changes

mergify Bot mentioned this pull request Sep 7, 2026

merge queue: checking #1795 on main (249fbd4), stacked on #1801 #1814

Closed

40 tasks

mergify Bot added the queued label Sep 7, 2026

mergify Bot merged commit 6a40504 into main Sep 7, 2026
22 of 42 checks passed

mergify Bot deleted the devs/jd/worktree-skill/add-maintainer-skill-cutting-release--588ca3b8 branch September 7, 2026 13:57

mergify Bot removed the queued label Sep 7, 2026

Navigation Menu

Uh oh!

docs(release): add a maintainer skill for cutting a release - #1795

docs(release): add a maintainer skill for cutting a release#1795
mergify[bot] merged 1 commit into
mainfrom
devs/jd/worktree-skill/add-maintainer-skill-cutting-release--588ca3b8

jd commented Sep 4, 2026

Uh oh!

mergify Bot commented Sep 4, 2026 •

edited

Loading

🟢 🤖 Continuous Integration

🟢 👀 Review Requirements

🟢 Enforce conventional commit

🟢 🔎 Reviews

🟢 📕 PR description

🟢 🚦 Auto-queue

Uh oh!

Copilot AI left a comment

Uh oh!

jd commented Sep 4, 2026

Uh oh!

jd commented Sep 4, 2026 •

edited

Loading

Uh oh!

jd commented Sep 4, 2026

Uh oh!

jd commented Sep 7, 2026

Uh oh!

kozlek left a comment

Uh oh!

mergify Bot commented Sep 7, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

jd commented Sep 4, 2026

Uh oh!

mergify Bot commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge Protections

🟢 🤖 Continuous Integration

🟢 👀 Review Requirements

🟢 Enforce conventional commit

🟢 🔎 Reviews

🟢 📕 PR description

🟢 🚦 Auto-queue

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

jd commented Sep 4, 2026

Uh oh!

jd commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Revision history

Uh oh!

jd commented Sep 4, 2026

Uh oh!

jd commented Sep 7, 2026

Uh oh!

kozlek left a comment

Choose a reason for hiding this comment

Uh oh!

mergify Bot commented Sep 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge Queue Status

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

4 participants

mergify Bot commented Sep 4, 2026 •

edited

Loading

jd commented Sep 4, 2026 •

edited

Loading

mergify Bot commented Sep 7, 2026 •

edited

Loading