# GitHub連携

PM on Railsの基本は、MCPでClaude Web / Claude Code / Codexから同じグラフを扱うことです。GitHub連携は、その開発の結果を外へ出すためのものです。ストーリーをIssueに書き出し、PRの状態をタスクへ戻せます。

![PM on RailsのGitHub連携設定。リポジトリ接続とPR紐付けの入口。導入前は完了報告が口頭だった。導入後はmainに届いたPRがタスク完了に戻る。](https://pmonrails.com/docs-img/gh-settings.png)

## できること

- **ストーリー → Issue** — ユーザーストーリーをGitHub Issueとして書き出し。紐付く受入シナリオを本文に列挙します。Markdownとして読める形なので、PM on Railsの外にも持ち出せます。
- **Issue → 反映** — Issue本文のGherkin編集をpullでPM on Railsに同期。最新状態をpushでIssueに再反映。
- **双方向同期** — `sync_story_to_github` で未発行なら新規作成、既存なら更新。
- **CIのテスト結果 → シナリオ** — workflowが残したシナリオ別レポート（artifact）を読み、シナリオタスクに合否を記録します（PATやsecretは不要）。設定手順は[テスト](https://pmonrails.com/docs/test-results.md)の「CIから自動で記録する」を見てください。

## PRとタスクの紐付け（3手段）

いずれかを満たすと、PRの状態変化でタスクが自動遷移します（既定ブランチへのマージ → done、featureブランチへのマージ → 待ち、open → review）。

1. **明示リンク** — タスクにPRを直接リンク（`link_pr`）。
2. **PR本文の識別行** — `PMR-Task: <UUID>` または `PMR-Story: <UUID>` を1行入れる。
3. **ブランチ命名** — `feat/<id8>-<slug>`（タスクIDの先頭8桁）。

> MCPでタスク着手すると、ブランチ名とPR本文用の識別行が返るので、UUIDを手で書く必要はありません（[MCP連携](https://pmonrails.com/docs/mcp.md)）。

- PRマージでタスクがdoneになると、**親ストーリーの状態も自動再計算**されます。
- **マージ先を区別します** — featureブランチ（stacked PRの親ブランチなど）へのマージは完了にせず、「ブランチにマージ済み（main未反映）」として待ち先を記録します。待ち先のブランチが既定ブランチに届いた時点で、待っていたタスクがまとめて完了になります。タスク画面のPRバッジで状態を確認できます。取りこぼしがあれば「PRとタスクの突き合わせ」（MCPの `reconcile_task_prs`）で回収できます。
- 着手後に仕様が変わった場合は「再確認が必要」をマーク（仕様乖離の検知）。

## 設定

GitHub AppはGitHubの組織ごとに1つで、同じワークスペースのプロジェクトで共有します。トークンやWebhookを手で設定する必要はありません。

1. **ワークスペース設定 > 連携 > GitHub** で「GitHubに追加」を押し、GitHubの画面で組織と対象リポジトリを選んで承認します（ワークスペースの管理者が行います）。
2. **プロジェクト設定 > 連携 > GitHub** で、このプロジェクトで使うリポジトリを選びます。

> GitHub側で対象リポジトリを絞ると、その組織のリポジトリを使う**全プロジェクト**に効きます。1つのプロジェクトのために、ほかのプロジェクトが使うリポジトリを外さないでください。

### GitHubの組織オーナーでないとき

GitHubの組織オーナーでない人が「GitHubに追加」を押すと、GitHubはインストールせず、組織オーナーへ依頼を送ります。PM on Railsの画面には「組織オーナーの承認待ち」と、オーナーに渡す依頼文（App名・要求する権限と用途）が出ます。

1. 依頼文をコピーして、組織オーナーに承認を頼みます。PM on RailsのGitHub Appが要求するのはリポジトリ単位の権限だけで、組織の権限は要求しません。
2. オーナーが承認したら、**ワークスペース設定 > 連携 > GitHub** の「GitHubで承認済みのインストールを取り込む」を押し、GitHubで本人確認をします。あなたがGitHub上でアクセスできるインストールだけが、このワークスペースに取り込まれます。

## ロックインしない

- ストーリーや設計書はMarkdownとして書き出せます。
- GitHub Issueにも同期できるため、開発チームの既存運用に載せられます。
- MCPでClaude Web / Claude Code / Codexから直接扱えるので、PM on Railsの画面以外からも使えます。

> マージでの自動クローズには、**GitHub Appの連携が前提**です（ワークスペース設定 > 連携 > GitHubで「GitHubに追加」し、プロジェクト設定 > 連携 > GitHubでリポジトリを選ぶ）。Webhookを手で登録する必要はありません。未連携だと自動遷移は効きません（手動リンクは可）。未接続時は、原因と設定方法を案内するエラーを返します。

---

https://pmonrails.com/docs/github