GitHub 連携
GitHub App を一度連携すれば、ブランチ・タイトル・本文にイシュー識別子を含む PR が該当イシューに自動で紐づきます。そして PR をマージするとイシューが Done に移動します。
設定 → GitHub で GitHub アカウントまたは組織を一度だけ連携してください。その後は、ブランチ名・タイトル・本文にイシュー識別子（例: AAC-123）を含むあらゆる pull request が該当するイシューに自動で紐づき、イシューサイドバーの Pull requests に表示され、PR がマージされるとイシューが Done に移動します。
イシューごとの設定はありません。フロー全体が識別子で駆動されます。
連携が行うこと
| 場所 | 動作 |
|---|---|
| 設定 → GitHub | ワークスペースの admin には、マスタートグル、Connect GitHub ボタン、機能スイッチ（PR サイドバー、Co-authored-by、自動紐づけ）を備えた GitHub タブが表示されます。インストール後は GitHub タブに戻ります。 |
| イシューサイドバー → Pull requests | このイシューに自動で紐づいたすべての PR が、タイトル、リポジトリ、状態（Open / Draft / Merged / Closed）、作成者とともに表示されます。行をクリックすると GitHub の該当 PR に移動します。 |
| Webhook（バックグラウンド） | すべての pull_request イベントで、AACWorkflow は PR 行を upsert し、PR からイシュー識別子をスキャンして、紐づけ行を（再）構築します。冪等性があり、同じ delivery を再送しても変化はありません。 |
| マージ時のステータス自動変更 | PR が merged に遷移すると、まだ Done でも Cancelled でもない、紐づいたすべてのイシューが Done に移動します。ステータス変更は source github_pr_merged でタイムラインに記録されます。 |
ミラーリングされるのは PR 自体のみです。コミット、オープンな PR のないブランチ ref、CI チェックの状態はモデル化されません。この連携は意図的に狭く設計されています。
識別子のマッチング方法
Webhook は次の順序で 3 つのフィールドから識別子を抽出します: PR head ブランチ、PR タイトル、PR 本文。マッチャーは次のとおりです。
- 大文字小文字を区別しません —
mul-123、AAC-123、Mul-123はすべてマッチします。 - 境界があります — 左側の
\bと右側の数字アンカーにより、v1.2-3のようなバージョン番号やメール形式の文字列を誤って拾わないようにしています。 - ワークスペーススコープに限定されます — そのワークスペース固有のイシュー prefixにのみマッチします。prefix が
AACのワークスペースでは、整数が別のイシューと一致してもFOO-1は無視されます。 - 重複が除去されます — 本文に
AAC-1, AAC-1と並べても、イシューは一度だけ紐づきます。
1 つの PR で複数のイシューを参照できます。Closes AAC-1, AAC-2 は PR を両方のイシューに紐づけ、マージすると両方が Done に進みます。
マージ時の Done 自動変更ルール
PR の merged フィールドが true に切り替わると、紐づいたすべてのイシューが評価されます。
| イシューの現在のステータス | 結果 |
|---|---|
done | 変化なし（すでに終了状態）。 |
cancelled | 変化なし — cancelled はユーザーが作業を明示的に放棄したことを意味するため、連携はこのシグナルを上書きしません。 |
それ以外すべて（todo、in_progress、in_review、blocked、backlog） | done に移動。 |
PR をマージせずにクローズした場合は、PR カードの状態が Closed に更新されるだけです。紐づいたイシューはそのまま維持されます — マージせずにクローズすることが何を意味するかはユーザーが決めるからです。
この動作はタイムライン上で system アクターに帰属します。イシューの購読者は、人がステータスを移動したときと同じように、ステータス変更に関するインボックス通知を受け取ります。
自動で紐づかないもの
- コミットメッセージ内の識別子 — ブランチ / タイトル / 本文のみがスキャンされます。
AAC-123: fix loginというタイトルのコミットは、同じ文字列が PR タイトルや本文にも現れない限り自動では紐づきません。 - PR コメント内の識別子 — PR 自体のメタデータのみがスキャンされ、後から付いた GitHub コメントは無視されます。
- App がインストールされていないリポジトリの PR — App がなければ、AACWorkflow は webhook をまったく受け取りません。
- PR をイシューに手動で紐づける — まだこのための UI はありません。チームの慣習で識別子を AACWorkflow が読まない場所に置いている場合は、PR タイトルや本文に追加してください。
連携解除
設定 → GitHub にはインストール一覧はありません — 既存のインストールは GitHub から直接管理します。
- GitHub から —
https://github.com/settings/installations（個人）またはhttps://github.com/organizations/<org>/settings/installations（組織）で AACWorkflow GitHub App をアンインストールします。AACWorkflow はinstallation.deletedwebhook を受け取ってリアルタイムで行を削除し、開いている Settings タブはリロードなしで更新されます。 - AACWorkflow 内部からの連携解除は admin 専用です — GitHub タブの連携解除コントロールは、admin 以外のユーザーには非表示です。マスター GitHub スイッチがオフでも利用可能なままなので、admin はワンクリックで機能を無効化した後でも、古いインストールを取り消せます。
連携解除後も、ミラーリングされた PR 行はデータベースに残り、過去のイシューサイドバーで何が紐づいていたかを引き続き表示しますが、そのインストールから新たに入ってくる webhook イベントは受理されなくなります。
権限と可視性
- 連携 / 連携解除にはワークスペースの owner または admin が必要です。member にはカードの説明は見えますが、Connect ボタンは見えません。
- イシューの Pull requests サイドバーは、そのイシューを閲覧できる誰にでも表示されます — イシュー詳細の他の部分と同じ権限です。
- GitHub App は pull request とメタデータへの読み取り専用アクセスを要求します。AACWorkflow はコミット、コメント、ステータスチェックを GitHub に書き戻すことはありません。
AACWorkflow Cloud 連携
GitHub 連携は AACWorkflow Cloud ですでに構成済みです。設定 → GitHub を開いて Connect GitHub をクリックし、アカウントまたは組織を連携してください。アクセスを許可するリポジトリを選び、インストールを完了します。
インストール後、ブランチ / タイトル / 本文にイシュー識別子を含む pull request は数秒以内に該当イシューへ自動的に紐づきます。
制限事項
現時点で知っておくべき、いくつかの粗い部分があります。
- まだ手動の紐づけ UI はありません — PR を紐づける唯一の方法は、ブランチ、タイトル、本文に識別子を置くことです。
- CI / チェック状態はありません — PR 自体のみがミラーリングされます。ビルド状態、レビューコメント、レビュアーは AACWorkflow には表示されません。
- マージ → Done ルールに対するワークスペースレベルの設定はありません — 固定のデフォルトです（
cancelledでない限りmerged → done）。ワークスペースでカスタマイズできるマッピングは将来の追加予定です。 - 1 つのイシューに複数の PR が紐づく場合、マージは保守的です — 2 つの PR がどちらも
AAC-123を参照していて最初の 1 つがマージされると、イシューはただちにDoneに移動します。進める前に紐づいたすべての PR が解決されるのを待つ後続の変更が進行中です。