labels-as-code

labels-as-code

将单个 GitHub 仓库的标签纳入版本控制，并让拉取请求的标签与发生变更的文件保持同步。

此技能的适用范围

关注事项	技能
在文件中跟踪单个仓库的标签集，按需或按计划同步	/labels-as-code（此技能）
根据路径为单个仓库的 PR 自动添加标签	/labels-as-code（此技能）
跨多个仓库的标签策略，从一个管理仓库进行协调	/safe-settings
Issue 表单、PR 模板、社区健康文件	/oss-hygiene

/safe-settings 也可以通过其 labels 块在组织范围内管理标签（通过 oldname 重命名、使用排除模式），并在每次 full-sync 运行时协调。若标签策略必须从一个中央管理仓库同步到多个仓库，请使用 /safe-settings。若范围仅限一个仓库，且文件位于该仓库中，请使用此技能。

配置内容

文件	用途
.github/labels.yml	标签集：每个标签的 name、color、description
.github/labeler.yml	actions/labeler 使用的路径到标签规则
.github/workflows/labels-sync.yml（可选）	按计划／在推送时将 .github/labels.yml 同步到仓库
.github/workflows/labeler.yml（可选）	在每个拉取请求上运行 actions/labeler

流程

1. 导出当前标签并比较差异

gh label list --json name,color,description

将导出结果与拟定的 .github/labels.yml 进行比较（如果文件尚不存在，则从 assets/labels.yml 创建）。在提出任何更改之前，打印差异——需要创建的标签、需要更改颜色或描述的标签，以及 GitHub 上存在但文件中缺少的标签。

2. 提出默认标签集

assets/labels.yml 提供了一套按前缀分组的起始标签：

• type/* — 每种 Conventional Commits 类型各一个标签（feat、fix、docs、style、refactor、perf、test、build、ci、chore、revert），与 /pr-title-lint 检查 PR 标题时使用的类型保持一致。
• priority/* — critical、high、medium、low。
• status/* — blocked、in-progress、needs-review。
• good first issue、help wanted — GitHub 自带的社区标准标签。
• dependencies — Dependabot 和手动依赖项升级 PR。
• breaking — 重大变更，在发布时标明。

阅读 references/label-scheme.md，了解完整表格，以及 type/* 和 breaking 如何映射到 /gh-bootstrap 的 .github/release.yml 类别（该文件的 Breaking changes 分类依据 breaking-change／breaking；其 Features／Fixes／Documentation／Internal 分类依据不带 type/ 前缀的 Conventional Commits 风格名称）。如果仓库已经使用 /gh-bootstrap 的发布说明，则要么在相关 PR 上保留这两种标签拼写，要么将 type/* 名称加入 release.yml 的类别列表中——该文件由 /gh-bootstrap 管理；此技能仅说明映射关系。

询问用户是要原样采用默认标签集、删减标签，还是从导出的标签开始。不要擅自决定——已有成熟标签集的仓库可能更倾向于保留自己的命名。

3. 同步选项

有两种方法可以将 .github/labels.yml 应用到仓库。执行任一种方法之前，都要先询问用户选择哪种。

此步骤和第 4 步中的工作流模板会固定使用 Node 24 的 Actions。在复制任一工作流之前，请确认所有自托管 Runner 的 Actions Runner 版本为 v2.327.1 或更高版本。GitHub 托管的 Runner 已满足此要求。

一次性同步

# Create or update one label (never deletes):
gh label create "<name>" --color "<hex>" --description "<text>" --force

# Clone another repo's full label set (adds only; existing labels keep
# their color/description unless the label doesn't exist yet):
gh label clone <owner>/<repo>

--force 会覆盖现有标签的颜色／描述；不会删除源文件中缺少的标签。未经用户明确授权，不得删除任何标签，且授权必须逐个标签确认——列出将要删除的标签，并在运行 gh label delete 前等待用户确认。

定时同步工作流

如需纠正偏差而无需人工运行 gh label create，请将 assets/labels-sync.yml 复制到 .github/workflows/labels-sync.yml。该工作流会运行 crazy-max/ghaction-github-labeler，这是已为此技能验证过的维护中操作（验证命令和当前固定的 SHA 见 references/label-scheme.md）。模板默认设置了 skip-delete: true——.github/labels.yml 中不存在的标签会保留，不会被删除。只有在用户明确授权删除后，才将 skip-delete 改为 false；步骤 1 中的差异会准确显示将删除哪些标签。模板每周通过 schedule 触发器运行；每次向 main 推送且变更了 .github/labels.yml 或工作流文件时运行；也可通过手动触发的 workflow_dispatch 运行。

EndBug/label-sync 是可行的替代方案，配置形式相同（从 YAML 文件同步，默认删除行为由选项控制）。固定版本前，请使用 gh api repos/{owner}/{repo} 和 references/label-scheme.md 中的标签到提交查询，验证任一操作的最新发布版本及 SHA——不要直接复用此技能中的 SHA，务必根据当前发布版本重新验证。

4. 基于路径为 PR 添加标签

将 assets/labeler.yml 复制到 .github/labeler.yml，并根据仓库的目录结构调整路径 glob——随附文件仅为示例，并非适用于所有场景的配置。将 assets/pr-labeler.yml 复制到 .github/workflows/labeler.yml；该工作流会运行 actions/labeler，并设置 permissions: contents: read, pull-requests: write（这是该操作读取变更文件并写入标签所需的最低权限）。

依赖固定的 SHA 前，请先验证：

LATEST=$(gh api repos/actions/labeler/releases/latest --jq '.tag_name')
gh api repos/actions/labeler/git/ref/tags/"$LATEST" --jq '.object.sha'

如果返回的 SHA 与 assets/pr-labeler.yml 中的注释不匹配，请同时更新 uses: 行及其末尾的版本注释——新 SHA 旁边留着过时注释，比没有注释更糟。

5. 验证

gh label list --json name,color,description

确认输出与 .github/labels.yml 完全一致（名称、颜色、描述均相同；用户选择保留为非托管的标签除外）。然后打开一个 PR，使其涉及 .github/labeler.yml 中匹配的路径，并确认预期标签已添加到该 PR；可查看 labeler.yml 工作流运行情况，或使用：

gh pr view <number> --json labels --jq '.labels[].name'

报告创建了什么、更新了什么、哪些内容保持不变，以及哪些标签（如果有）仍待用户授权删除。

此技能不适用于

• 在多个仓库之间协调组织级标签策略——请使用 /safe-settings
• Issue 表单、PR 模板或其他社区健康文件——请使用 /oss-hygiene
• 未经用户逐个明确授权就删除标签
• 分支保护、合并设置或发布说明配置——请使用 /gh-bootstrap

注意事项

• gh label create --force 可以幂等地更新颜色和描述，但绝不会删除标签。删除需要单独、明确地调用 gh label delete——未事先询问时，绝不要将其加入常规同步流程。
• 除非设置了 skip-delete: true，否则 crazy-max/ghaction-github-labeler 会删除 YAML 文件中不存在的标签。将工作流接入标签未被该文件完整列出的仓库前，请先确认此标志。
• 当 PR 不再涉及相应路径时，actions/labeler 的 sync-labels 输入会移除基于路径添加的标签。除非用户希望这样做，否则请保留其默认值（false）——这属于自动删除行为。
• gh label create --color 的颜色值使用不带 # 的裸十六进制字符串；.github/labels.yml 通常也按惯例存储不带 # 的十六进制值，以适配 actions/labeler 的上游生态，但 crazy-max/ghaction-github-labeler 两种格式都接受。请在仓库的文件中统一使用一种格式。
• 使用 gh label create --force 重命名标签并不会真正重命名——它会创建一个新标签。重命名请使用 gh label edit <old-name> --name <new-name>；如果同步工具的配置格式支持，也可使用 from_name:。