pr-title-lint

pr-title-lint

搭建一项 CI 检查，拒绝不符合 Conventional Commits 规范的拉取请求标题。

当 squash merge 使用 PR 标题作为提交主题时，这一点尤为重要： 未检查的标题会在 PR 合并的那一刻成为永久历史记录。

适用场景

关注事项	技能
将仓库切换为仅允许 squash merge，并使用 PR 标题作为提交消息	gh-bootstrap
在 CI 中强制执行 PR 标题格式	pr-title-lint（此技能）
将检查名称添加到规则集的必需状态检查中	gh-bootstrap
发布带版本号的版本	release
本地提交消息钩子（通过 prek 使用 commitlint）	prek

流程

1. 检测 squash merge 是否使用 PR 标题作为提交消息

REPO="$(gh repo view --json nameWithOwner --jq '.nameWithOwner')"
gh api "repos/$REPO" --jq '.squash_merge_commit_title'

PR_TITLE 表示 squash 提交主题会原样采用 PR 标题，因此默认分支上的 git log --oneline 会变成 PR 标题列表。未检查的标题会在 PR 合并的那一刻， 将拼写错误、缺少类型或含糊的摘要变成永久历史记录。这是添加此检查的最有力 理由；不过，如果值为 COMMIT_OR_PR_TITLE 或未设置，也应主动提出搭建此检查， 因为标题仍有可能成为历史记录。

2. 检测是否已有检查

grep -rl 'action-semantic-pull-request' .github/workflows/ 2>/dev/null
grep -rl 'commitlint' .github/workflows/ .commitlintrc* commitlint.config.* 2>/dev/null

如果某个工作流已经使用 action-semantic-pull-request 检查 PR 标题，或者某个 commitlint 任务已经检查 PR 标题（而不仅仅是提交消息），则停止操作并报告已有检查， 不要添加重复检查。

3. 搭建工作流

将 assets/pr-title.yml 复制到 .github/workflows/pr-title.yml。该工作流通过提交 SHA 固定 amannn/action-semantic-pull-request 的版本（而不是使用浮动标签），并包含：

• permissions: pull-requests: read — 遵循最小权限原则；该操作只需读取 PR 标题
• on.pull_request.types: [opened, edited, synchronize, reopened] — 每当标题或 PR 本身发生 变化时，都会重新运行检查
• merge_group 触发器和作业级别的 if: github.event_name == 'pull_request' — 仅在 PR 上验证标题，因为合并组事件没有 PR 标题； 在 merge_group 上会跳过该作业，跳过的作业会报告成功
• 已注释的 types 和 scopes 列表，以及一个 subjectPattern 示例，供用户取消注释并按需调整
• requireScope: false — 大多数仓库不需要强制要求 scope

覆盖现有的 .github/workflows/pr-title.yml 前，先征求同意；并先展示差异。

完整的 Conventional Commits 摘要、squash merge 的引用资料以及该操作的配置选项，请参阅 references/conventional-commits.md。

4. 可选：通过 prek 检查提交消息

如果用户还想检查本地提交消息（而不仅仅是 PR 标题），应使用 commit-msg 钩子，而不是 GitHub Actions 作业。请引导他们使用 prek，并提供 assets/commitlint.config.example 作为 prek 集成的起始配置。

5. 将检查设为必需（可选，需授权）

将 pr-title-lint 的检查名称添加到规则集的必需状态检查中，是 gh-bootstrap 的职责，而不是此技能的职责。将这一步交给 gh-bootstrap，并在写入任何规则集之前获得用户明确授权——切勿在未事先询问的情况下，将必需检查添加到正在使用的规则集中。

在将检查设为必需之前，告知用户合并队列的相关情况。如果分支使用合并队列，GitHub 会等待 merge_group 事件上的每项必需检查。未配置 merge_group 触发器的工作流不会报告该检查。队列会等待该检查，然后移除 PR，导致合并失败。保留模板中的 merge_group 触发器和作业级 if。如果用户移除了该触发器，请在将检查设为必需之前将其加回。来源： 管理合并队列 和 处理已跳过但必需的检查。

6. 验证

创建（或请用户创建）一个标题不符合 Conventional Commits 的拉取请求，例如 updated stuff，并确认 pr-title 检查失败且显示清晰的错误信息。然后将 PR 标题改为类似 fix: correct typo 的内容，并确认检查变为绿色。

此技能不适用于

• 配置仅限 squash 的合并方式或 squash_merge_commit_title — gh-bootstrap
• 将检查名称添加到规则集的必需状态检查中 — gh-bootstrap
• 创建或发布版本 — release
• 本地 pre-commit 或提交消息钩子 — prek