Back to Details

release-status

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

release-status

release-status

Diagnose the release-please pipeline and report why a release did or didn't fire — read-only. The skill gathers four independent signals via 
gh
and 
git
, prints a structured report, and surfaces the remediation for each. It writes nothing: no commits, no labels, no PR edits, no releases.
诊断release-please流水线并报告发布触发或未触发的原因——仅可读。该技能通过
gh
和
git
收集四个独立信号，打印结构化报告，并给出每个问题的修复建议。它不会进行任何写入操作：无提交、无标签修改、无PR编辑、无发布操作。

Relationship to 
/send-it

与
/send-it
的关系

This is a sibling of 
send-it
, not invoked by it. 
send-it
is the pre-merge ship flow — it stops at In Review (opens the PR, transitions the Linear issue). 
release-status
picks up after merge: it inspects the state of 
main
, the release PR, and the tags to explain what the release machinery is doing. The two never call each other. This skill may reference 
send-it
in prose (e.g. "the PR title 
send-it
composed is the bump signal"), but it never runs it.
这是
send-it
的同级工具，而非由其调用。
send-it
是合并前的交付流程——它会在审核中阶段停止（打开PR，流转Linear工单）。
release-status
则在合并后启动：它检查
main
分支、发布PR和标签的状态，以解释发布机制的运行情况。两者不会互相调用。该技能可能在文本中提及
send-it
（例如：“
send-it
生成的PR标题是版本升级信号”），但绝不会运行它。

What it inspects

检查内容

SignalWhat it answersHow to read / fix it
Version previewWhat bump and version would the merged Conventional-Commit PR titles since the last tag produce?
feat:
→minor, 
fix:
/
perf:
/
revert:
→patch, 
!
/
BREAKING CHANGE:
→major; 
docs
/
chore
/
ci
/
refactor
/
test
/
build
/
style
→none. The strongest wins. 
none
means nothing release-triggering has merged since the last tag — no release will cut.
Release PRIs the 
release-please--branches--main
PR open, and is its required check (
🔬 Build & Lint
) green?		If open and green, the orchestrator can squash-merge it. If the check is pending/red, the merge is blocked — chase that check. If none is open, release-please hasn't opened one (often because nothing release-triggering merged, or the pipeline is stalled — see below).
Stale 
autorelease: pending
Does the last merged release PR still carry the 
autorelease: pending
label?		This is the recurring stall: when a merged release PR keeps that label, release-please aborts the next release and the pipeline silently stops firing. Remediation: remove the label from that PR, then re-run the orchestrator (or wait for its cron tick).
Tag-vs-version parityDoes a 
v<package.json version>
tag already exist?		This is the 
release.yml
version-vs-tag gate. Tag exists → clean no-op (this version is already published). Tag missing → publishing is pending for that version (the gate would run the publish path on the next 
main
push).
信号解决的问题解读与修复方式
版本预览自上次标签以来，合并的Conventional-Commit PR标题会触发怎样的版本升级和新版本号？
feat:
→次要版本，
fix:
/
perf:
/
revert:
→补丁版本，
!
/
BREAKING CHANGE:
→主要版本；
docs
/
chore
/
ci
/
refactor
/
test
/
build
/
style
→无版本变更。优先级最高的类型决定最终结果。
none
表示自上次标签以来没有合并触发发布的内容——不会触发任何发布。
发布PR
release-please--branches--main
PR是否已打开，且其必填检查（🔬 Build & Lint）是否通过？		若已打开且检查通过，编排器可 squash-merge 该PR。若检查处于待处理/失败状态，合并会被阻塞——需跟进该检查。若未打开任何PR，说明release-please未创建PR（通常是因为没有合并触发发布的内容，或流水线已停滞——见下文）。
陈旧的
autorelease: pending
标签		最近合并的发布PR是否仍带有
autorelease: pending
标签？		这是反复出现的停滞问题：当合并后的发布PR仍保留该标签时，release-please会中止下一次发布，流水线将静默停止触发。修复方式：移除该PR上的标签，然后重新运行编排器（或等待其定时触发）。
标签与版本一致性是否已存在
v<package.json版本>
标签？		这是
release.yml
中的版本与标签校验关卡。标签已存在→无操作（该版本已发布）。标签不存在→该版本的发布处于待处理状态（下次
main
分支推送时，关卡会执行发布流程）。

Configuration

配置

Four knobs live in 
config.json
beside this file, vendored from the tracked 
config.example.json
 template (the runtime 
config.json
is generated per consumer and is not itself tracked). Read 
config.json
at the start of a run and use its values throughout. Edit your copied 
config.json
to match the consuming repo.
KeyMeaningDefault
mainBranch
The trunk release-please releases from.
main
releaseBranch
The branch release-please opens its release PR on.
release-please--branches--main
requiredCheck
The exact name (incl. emoji) of the required status check the orchestrator polls before merging the release PR.
🔬 Build & Lint
stalePendingLabel
The label release-please applies to a release PR while a release is in flight; stale when it lingers on a merged PR.
autorelease: pending
本文件旁的
config.json
中有四个配置项，源自跟踪的
config.example.json
模板（运行时的
config.json
由每个使用者生成，本身不被跟踪）。运行开始时会读取
config.json
并全程使用其值。编辑你复制的
config.json
以匹配目标仓库。
配置项含义默认值
mainBranch
release-please用于发布的主干分支
main
releaseBranch
release-please用于打开发布PR的分支
release-please--branches--main
requiredCheck
编排器在合并发布PR前轮询的必填状态检查的完整名称（含表情符号）
🔬 Build & Lint
stalePendingLabel
release-please在发布进行中时添加到发布PR的标签；当标签残留在已合并的PR上时即为陈旧标签
autorelease: pending

Usage

使用方法

Run the bundled helper. Its path is relative to this skill's own directory (the one holding this 
SKILL.md
and 
config.json
) — resolve it from there, not from the consuming repo's root, or the run fails with 
ENOENT
.
Human-readable report — the default:
bash
node scripts/release-status.mjs
Machine-readable JSON — for piping into another step:
bash
node scripts/release-status.mjs --json
Explicit repo — when not run from inside the target checkout:
bash
node scripts/release-status.mjs --repo acme-skunkworks/agent-skills
Self-test — run the bundled offline assertions (no network, no 
gh
); a quick way to confirm the script is healthy after install:
bash
node scripts/release-status.mjs --self-test
--help
(alias 
-h
) prints the full usage.
运行捆绑的辅助脚本。其路径相对于本技能所在目录（即包含此
SKILL.md
和
config.json
的目录）——需从此目录解析路径，而非从目标仓库的根目录，否则会因
ENOENT
错误运行失败。
人类可读报告——默认模式：
bash
node scripts/release-status.mjs
机器可读JSON——用于管道传输到其他步骤：
bash
node scripts/release-status.mjs --json
指定仓库——不在目标仓库目录内运行时：
bash
node scripts/release-status.mjs --repo acme-skunkworks/agent-skills
自检——运行捆绑的离线断言（无网络，无需
gh
）；这是安装后快速确认脚本是否正常的方法：
bash
node scripts/release-status.mjs --self-test
--help
（别名
-h
）会打印完整使用说明。

Process

流程

Step 1 — Confirm prerequisites

步骤1——确认前置条件

gh auth status
must pass, and you must be inside (or pass 
--repo
for) the target repository. The helper reads the root 
package.json
version, the local tags, and queries 
gh
for the release PR and merged PRs.
gh auth status
必须通过，且你必须在目标仓库目录内（或通过
--repo
指定仓库）。辅助脚本会读取根目录的
package.json
版本、本地标签，并通过
gh
查询发布PR和已合并的PR。

Step 2 — Run the helper and read the four signals

步骤2——运行辅助脚本并读取四个信号

bash
node scripts/release-status.mjs
Read each block in order: version preview, release PR, stale 
autorelease: pending
, tag-vs-version parity. The helper only fetches and prints — running it never changes anything.
bash
node scripts/release-status.mjs
按顺序读取每个模块：版本预览、发布PR、陈旧的
autorelease: pending
标签、标签与版本一致性。辅助脚本仅进行获取和打印——运行它不会修改任何内容。

Step 3 — Interpret and advise (do not act)

步骤3——解读并给出建议（不执行操作）

Map the signals to a diagnosis. The common shapes:
  • "A release should have fired but didn't." Check the stale-pending block first — a lingering 
    autorelease: pending
    on the last merged release PR is the usual culprit (release-please aborts). If that's clear, check whether the version preview is 
    none
    (nothing release-triggering merged) or whether the release PR is open-but-its-check-is-red (blocked at the gate).
  • "What version cuts next?" Read the version-preview block: the bump and the resulting 
    next
    version. 
    none
    means no release.
  • "Is publishing pending?" Read the parity block: a missing 
    v<version>
    tag means the next 
    main
    push runs the publish path; a present tag means a clean no-op.
将信号映射到诊断结果。常见情况：
  • “应该触发发布但未触发”：首先检查陈旧标签模块——最近合并的发布PR上残留
    autorelease: pending
    标签是常见原因（release-please会中止）。若该模块无问题，检查版本预览是否为
    none
    （没有合并触发发布的内容），或发布PR已打开但检查失败（在关卡处被阻塞）。
  • “下一个要发布的版本是什么？”：查看版本预览模块：版本升级类型和对应的
    next
    版本号。
    none
    表示不会触发发布。
  • “发布是否处于待处理状态？”：查看一致性模块：缺少
    v<version>
    标签意味着下次
    main
    分支推送会执行发布流程；标签已存在则表示无操作。

Step 4 — Report, with remediation

步骤4——报告诊断结果及修复建议

Summarise the diagnosis and surface the remediation the helper prints, but do not perform it — this skill is advisory. For the stale-pending stall, the fix is to remove the label from the merged release PR and re-run the orchestrator; state that as the recommended next action and leave it to the human (or a write-capable skill) to carry out.
总结诊断结果并给出辅助脚本打印的修复建议，但不要执行操作——本技能仅提供咨询。对于陈旧标签导致的停滞，修复方式是移除合并发布PR上的标签并重新运行编排器；将此作为建议的下一步操作，由人工（或具备写入权限的技能）执行。

Important rules

重要规则

  • Read-only / advisory. Never remove a label, edit a PR, push a tag, or trigger a release. Gather, diagnose, and recommend — the human or a write-capable tool acts.
  • Not a 
    send-it
    step.     This skill is never invoked by 
    send-it
    and never invokes it. It inspects post-merge 
    main
    ; 
    send-it
    stops at In Review.
  • Evidence, not guesses. Report what the helper actually returned. If 
    gh
    fails (auth, rate limit, permissions), report the failure — never treat "couldn't fetch" as "no release PR" or "no stall".
  • Mirror, don't import. The bump rules are re-implemented here to keep the bundle standalone (ADR-0001 self-containment); they mirror 
    send-it
    's 
    derive-bump.mjs
    and CLAUDE.md but never reach into a sibling skill.
  • 仅可读/咨询：永远不要移除标签、编辑PR、推送标签或触发发布。仅收集信息、诊断问题并给出建议——由人工或具备写入权限的工具执行操作。
  • 不是
    send-it
    的步骤    ：本技能绝不会被
    send-it
    调用，也绝不会调用
    send-it
    。它检查合并后的
    main
    分支；
    send-it
    在审核中阶段停止。
  • 基于证据，而非猜测：报告辅助脚本实际返回的结果。若
    gh
    调用失败（认证、速率限制、权限），报告该失败——绝不能将“无法获取”视为“无发布PR”或“无停滞”。
  • 镜像实现，不依赖导入：此处重新实现了版本升级规则以保持捆绑包独立（ADR-0001自包含性）；这些规则与
    send-it
    的
    derive-bump.mjs
    和CLAUDE.md一致，但绝不会依赖同级技能。

Error handling

错误处理

  • gh auth status
    fails → stop and tell the user to run 
    gh auth login
    .
  • The helper exits non-zero (rate limit, permissions, GraphQL/REST error) → report it; do not fabricate signals. Fall back to a manual 
    gh pr list --state merged --head <releaseBranch> --json labels
    to inspect the stale-pending label by hand.
  • No tags yet (a never-released repo) → the version preview counts all merged PRs, and the parity block reports the first 
    v<version>
    tag as pending. That is expected for the bootstrap release.
  • gh auth status
    失败→停止并告知用户运行
    gh auth login
    。
  • 辅助脚本非零退出（速率限制、权限、GraphQL/REST错误）→报告该错误；不要编造信号。可手动运行
    gh pr list --state merged --head <releaseBranch> --json labels
    来手动检查陈旧标签。
  • 尚无标签（从未发布过的仓库）→版本预览会统计所有已合并的PR，一致性模块会报告首个
    v<version>
    标签处于待处理状态。这对于首次发布是正常情况。

Arguments

参数

$ARGUMENTS
$ARGUMENTS