GitHub 連携

pull request を Multica のタスクに紐づけ、開発の進捗をタスクから確認します。

GitHub を接続すると、Multica はタスク番号を使って pull request を自動的に紐づけます。タスクの詳細画面から、PR の状態、変更規模、CI の結果、マージ競合を直接確認できます。

GitHub 連携が読み取るのは、インストール時に許可されたリポジトリだけです。コード、コメント、status check を書き込むことはありません。

セルフホスト版 Multica では、セルフホストの Forgejo、Gitea、GitLab インスタンスも同時に接続できます。PR の自動紐づけ、マージ時の Done への変更、CI 表示を同じように利用できます。設定 → 連携 → Git ホスティングから設定してください。詳しくはセルフホスト Git ホスティングを参照してください。Multica Cloud にはこの項目はありません。

GitHub を接続する

ワークスペースの owner または admin が接続できます。

設定 → GitHub を開きます。
GitHub 連携のメインスイッチを有効にします。
GitHub に接続をクリックします。
GitHub でアカウントまたは organization を選び、すべてのリポジトリか指定したリポジトリを許可します。
インストールが完了したら Multica に戻ります。

接続状態は同じページに表示されます。通常のメンバーは状態を確認できますが、接続、切断、スイッチの変更はできません。

GitHub 接続は、Multica がどのリポジトリから PR イベントを受け取るかを決めます。コードリポジトリ設定は、エージェントが作業を実行するときに選べるリポジトリを決めます。用途が異なるため、それぞれ設定する必要があります。

機能スイッチ

設定 → GitHub には 4 つのスイッチがあります。

スイッチ	機能
GitHub 連携	メインスイッチ。無効にすると下の 3 項目は機能しなくなりますが、GitHub App の接続は解除されません。
PR サイドバー	紐づいた pull request をタスクの詳細画面に表示します。
Co-authored-by	エージェントが作成する commit に `Co-authored-by: multica-agent <[email protected]>` を追加します。
PR の自動紐づけ	PR のブランチ名、タイトル、本文からタスク番号を検出します。
PR カード → CI とマージ可否	紐づいた各 PR について、Multica は認証済みの GitHub API スナップショットを取得し、その CI ステータスとマージ可否をカードにミラーリングします（下記の PR カードに表示される内容を参照）。

PR をタスクに紐づける

最も簡単な方法は、タスク番号をブランチ名または PR タイトルへ入れることです。タスクが MUL-123 の場合:

mul-123-fix-login-redirect

MUL-123 ログイン後のリダイレクトを修正

Multica は大文字と小文字を区別せず、現在のワークスペースのタスク接頭辞だけを照合します。1 つの PR を複数のタスクに紐づけることもできます。

タスク番号を PR 本文だけに書く場合は、GitHub の closing keyword を使ってください。

Closes MUL-123
Fixes MUL-123
Resolves MUL-123

本文に Related to MUL-123 のような通常の参照を書いただけでは、そのタスクの作業 PR として表示されません。Commit message と PR コメントも紐づけの対象外です。

タスクから PR を確認する

紐づけが完了すると、PR がタスク詳細の Pull requests セクションに表示されます。各項目には次の情報が含まれます。

リポジトリ、番号、タイトル、作成者
Open、Draft、Merged、Closed の状態
追加行数、削除行数、変更ファイル数
CI の状態: すべて成功した check の件数、失敗した check の名前、実行中の check の件数。check が 1 つも設定されていない PR ではこの項目を表示せず、「check なし」を成功として扱いません。
マージ可能性: GitHub がマージ状態を clean と報告した場合だけマージ可能。ほかに競合、blocked、behind を表示します。

CI の状態とマージ可能性は、Multica が GitHub API から取得したスナップショットで、互いに独立しています。マージ済みまたはクローズ済みの PR では、この 2 項目を表示しません。GitHub が一時的に利用できない場合、カードを空にせず、前回のスナップショットを古い情報として表示します。

項目をクリックすると GitHub の PR が開きます。PR サイドバーを無効にしてもこのセクションが非表示になるだけで、接続は解除されません。

PR のマージで Done になる条件

PR がマージされても、必ずしもタスクが完了するわけではありません。Multica がタスクを Done に変更するのは、次の条件をすべて満たす場合だけです。

紐づいたマージ済み PR のうち少なくとも 1 つで、Closes MUL-123 のように closing keyword の直後にタスク番号を指定している。Closes login MUL-123 のように間に別の単語がある形式は無効です。
そのタスクに、Open または Draft の作業 PR がほかに残っていない。本文中の通常の参照は作業 PR に含みません。
タスクの現在の状態が done または cancelled ではない。

そのため、ブランチ名やタイトルに MUL-123 を含めるだけで紐づけは作成されますが、それだけではタスクを完了にしません。PR をマージせずにクローズした場合も、タスクは完了しません。

状態の変更はシステム操作としてタイムラインに記録され、そのタスクを購読しているメンバーへ通知されます。

複数のワークスペース

同じ GitHub App installation を複数の Multica ワークスペースへ接続できます。GitHub イベントは各ワークスペースにそれぞれ送られ、各ワークスペースのタスク接頭辞に従って照合されます。

たとえば、1 つの PR が MUL-1 と ENG-2 の両方を参照している場合、異なる接頭辞を持つ 2 つのワークスペースでそれぞれ紐づけられます。ワークスペース間で相手のタスクが見えることはありません。

接続を解除する

設定 → GitHub の接続解除をクリックすると、現在の Multica ワークスペースと installation の関係だけが削除されます。GitHub から App がアンインストールされることはありません。既存の PR 記録は保持されますが、新しいイベントはこのワークスペースに届かなくなります。

GitHub 側のリポジトリアクセスを取り消す場合は、個人または organization の GitHub App installations ページで App をアンインストールするか、リポジトリの範囲を変更してください。App をアンインストールすると、その installation に接続していたすべての Multica ワークスペースがイベントを受信しなくなります。

セルフホスト設定

Multica Cloud ではこのセクションの作業は不要です。セルフホスト環境では、自分の GitHub App を先に作成します。

1. GitHub App を作成する

GitHub の Developer settings → GitHub Apps で App を作成し、次の値を入力します。

フィールド	値
Homepage URL	Multica のフロントエンド URL。例: `https://multica.example.com`
Callback URL	空欄
Setup URL	`https://<api-host>/api/github/setup`。Redirect on update を有効にする
Webhook URL	`https://<api-host>/api/webhooks/github`
Webhook secret	長期保管するランダムな文字列

Repository permissions:

権限	レベル
Metadata	Read-only
Contents	Read-only。PR スナップショットのクエリが head commit・マージ可否・CI ロールアップをまとめて読み取るために必要
Pull requests	Read-only
Checks	Read-only。CI の状態表示に使用
Commit statuses	Read-only。legacy status 形式の CI 集計に使用

次のイベントを購読します。

Pull request
Check suite、Check run、Status。CI とマージ可能性を更新するために使用します。

Multica で CI を表示しない場合は、Checks と Commit statuses の権限、および関連イベントの購読を省略できます。ただし Contents は必須です。付与しないとスナップショットのクエリ自体が失敗し、PR カードからマージ状態も消えます。

必要なのは Webhook secret であり、OAuth Client secret ではありません。GitHub と Multica に入力した Webhook secret が異なる場合、GitHub delivery は 401 invalid signature を返します。

2. 環境変数を設定する

App の公開 URL から slug を確認します。たとえば https://github.com/apps/multica-acme の slug は multica-acme です。

GITHUB_APP_SLUG=multica-acme
GITHUB_WEBHOOK_SECRET=<webhook secret entered when creating the App>
FRONTEND_ORIGIN=https://multica.example.com

GITHUB_APP_SLUG と GITHUB_WEBHOOK_SECRET のいずれかがない場合、接続ボタンは無効になり、webhook エンドポイントもイベントを拒否します。

次の 2 つの変数は、PR カードに CI の状態とマージ可能性を表示するために必要です。Multica は App として認証し、スナップショットを取得します。

GITHUB_APP_ID=<numeric GitHub App ID>
GITHUB_APP_PRIVATE_KEY=<complete PEM private key, including BEGIN/END lines and newlines>

秘密鍵は GitHub App の Private keys → Generate a private key から生成します。設定しない場合も連携は安全に縮退します。PR のミラー、タスクの自動紐づけ、マージ時の Done への変更は動作しますが、PR カードに CI やマージ状態は表示されません。

3. データベースを更新して接続する

既存のデプロイをアップグレードする場合は、通常のデータベースマイグレーションを先に実行します。

make migrate-up

API サービスを再起動し、設定 → GitHub から接続します。

よくある問題

接続ボタンを使用できない: GITHUB_APP_SLUG と GITHUB_WEBHOOK_SECRET が API プロセスに設定されていることを確認します。
Webhook が 401 を返す: GitHub App と API が同じ Webhook secret を使っていることを確認し、GitHub の Recent Deliveries から再配信します。
PR が紐づかない: リポジトリが App の許可範囲にあること、PR の自動紐づけが有効であること、番号が現在のワークスペースのものかを確認します。
本文に番号を書いても表示されない: Closes MUL-123 を使うか、番号をブランチ名または PR タイトルに入れます。
CI の状態がない: GITHUB_APP_ID と GITHUB_APP_PRIVATE_KEY が設定済みで、App に Contents、Checks、Commit statuses の read-only 権限があり、関連イベントを購読していることを確認します。Contents が欠けるとスナップショット全体が失敗し、PR カードには CI もマージ状態も表示されません。インストール済み App に権限を追加した場合は、各 installation の所有者が GitHub 上で承認するまで有効になりません。
PR のマージ後もタスクが完了しない: PR で closing keyword を使っていることと、Open または Draft の関連 PR がほかに残っていないことを確認します。

次のステップ

タスク — 状態遷移と PR マージによる Done への変更
プロジェクトリソース — エージェントが実行時に使えるリポジトリ
環境変数 — セルフホスト GitHub App の全設定

このページの内容