pr-title-lint

pr-title-lint

Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) に従っていないプルリクエストのタイトルを拒否する CI チェックをスキャフォールドします。

特に、スカッシュマージで PR タイトルをコミットの件名として使う場合に重要です。チェックされていないタイトルは、PR がマージされた瞬間に恒久的な履歴になります。

このスキルの位置づけ

懸念事項	スキル
PR タイトルをコミットメッセージにして、リポジトリをスカッシュマージのみに切り替える	gh-bootstrap
CI で PR タイトルの形式自体を強制する	pr-title-lint（このスキル）
ルールセットの必須ステータスチェックにチェック名を追加する	gh-bootstrap
バージョン付きリリースを作成する	release
ローカルのコミットメッセージフック（prek 経由の commitlint）	prek

プロトコル

1. PR タイトルをコミットメッセージにするスカッシュマージかどうかを検出する

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

PR_TITLE の値は、スカッシュコミットの件名が 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

ワークフローがすでに PR タイトルに対して action-semantic-pull-request を実行している場合、または commitlint ジョブが PR タイトル（コミットメッセージだけではなく）をすでにチェックしている場合は、重複するチェックを追加せず、停止して既存のチェックを報告してください。

3. ワークフローをスキャフォールドする

assets/pr-title.yml を .github/workflows/pr-title.yml にコピーします。このファイルでは amannn/action-semantic-pull-request をコミット SHA で固定しており（変動するタグではありません）、次の設定が含まれています。

• permissions: pull-requests: read — 最小権限です。このアクションに必要なのは PR タイトルの読み取りだけです。
• on.pull_request.types: [opened, edited, synchronize, reopened] — タイトルまたは PR 自体が変更されるたびにチェックを再実行します。
• ジョブレベルの if: github.event_name == 'pull_request' を指定した merge_group トリガー — このジョブは PR の場合にのみタイトルを検証します。マージグループイベントには PR タイトルがないためです。merge_group ではジョブがスキップされ、スキップされたジョブは成功として報告されます。
• コメントアウトされた types と scopes のリスト、およびユーザーがコメントを解除して調整できる subjectPattern の例
• requireScope: false — ほとんどのリポジトリでは、スコープを必須にする必要はありません。

既存の .github/workflows/pr-title.yml を上書きする場合は、事前に確認を求め、まず差分を表示してください。

Conventional Commits の概要、スカッシュマージに関する引用、アクションの設定オプションの全容については、references/conventional-commits.md を参照してください。

4. オプション：prek 経由でコミットメッセージをチェックする

ユーザーが PR タイトルだけでなくローカルのコミットメッセージもチェックしたい場合は、GitHub Actions のジョブではなく、commit-msg フックを使用します。prek を案内し、prek に組み込むための設定例として assets/commitlint.config.example を提案してください。

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_merge_commit_title の設定 — gh-bootstrap
• ルールセットの必須ステータスチェックへのチェック名の追加 — gh-bootstrap
• リリースの作成または公開 — release
• ローカルのコミット前フックまたはコミットメッセージフック — prek