GitHub 連携

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

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

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

GitHub を接続する

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

1. 設定 → コード を開きます。
2. GitHub の行で GitHub に接続をクリックします。
3. GitHub でアカウントまたは organization を選び、すべてのリポジトリか指定したリポジトリを許可します。
4. インストールが完了したら Multica に戻ります。

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

機能スイッチ

設定 → コード の プルリクエストとタスク には次の設定があります。GitHub の行の ⋯ メニューで GitHub 機能を一時停止 すると、下の 3 項目は機能しなくなりますが、GitHub App の接続は解除されません。

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 のような通常の参照を書いただけでは、そのタスクへまったく紐づきません。Commit message と PR コメントも紐づけの対象外です。

手動で紐づけることもできます。タスクの Pull requests セクションで + をクリックし、PR の URL を貼り付けます。PR をタスクから外すには、その行の ⋯ メニューから タスクから外す を選びます。以後、Multica がタイトルやブランチから再び紐づけることはありません。

タスクから 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 が一時的に利用できない場合、カードを空にせず、前回のスナップショットを古い情報として表示します。

リストの下には、次に何が起きるかを 1 行で表示します。たとえば「#19 がマージされると 完了 に変更」や、マージされずにクローズされた PR です。ワークスペースが「変更しない」に設定されている場合や、タスクがすでに変更先のステータスにある場合は表示されません。

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

PR マージ後のステータス変更

PR がマージされても、必ずしもタスクが完了するわけではありません。そのため、マージ後に何をするかはワークスペースが決めます: 設定 → コード → PR マージ後のタスクのステータス。Done（新しいワークスペースの既定値）、ほかの「開始済み」「完了」カテゴリーのステータス（「回帰テスト待ち」のようなカスタムステータスも可）、または 変更しない を選べます。この設定ができる前からあるワークスペースは、これまでの挙動を保ちます。マージしても必ずタスクが完了していたわけではない場合、初期値は 変更しない です。

次の条件をすべて満たすと、タスクは選んだステータスに変わります。

1. タスクに紐づく PR がすべて Merged である。Open や Draft の PR が残っているとタスクは待機を続けます。マージされずにクローズされた PR も、タスクから外すまで同様です。
2. タスクが done または cancelled ではなく、Triage 中でもなく、すでに変更先のステータスでもなく、このタスクだけ変更をオフにしていない（Pull requests → ⋯ → PR マージ後もステータスを変えない）。

PR の紐づけ方は結果に影響しません。タイトル、ブランチ名、本文の Closes MUL-123 はどれも紐づけるだけで、マージ後の動作は決めません。PR がタスクの一部しか納品しない場合や、マージ後にリリースや確認が必要な場合は、そのタスクの Pull requests メニューからステータスを変えないように設定します。

判定は PR イベントがタスクに関わったときだけ行います。紐づいた PR のマージ、紐づけの追加、紐づけの解除です。タスクを再度開いても元には戻らず、次に紐づいた PR がマージされたときに変更されます。設定を変えても、以前にマージされたタスクには影響しません。

状態の変更は関連する PR を示したシステム操作としてタイムラインに記録され、そのタスクを購読しているメンバーへ通知されます。この設定はセルフホスト Git ホスティングを含むすべてのコードホストで共通です。

複数のワークスペース

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

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

同じ番号が接続中の複数のワークスペースでタスクに一致する場合（接頭辞が同じときに起こり得ます）、Multica はどのワークスペースでも自動では紐づけません。関係のないタスクがマージで完了しないようにするためです。正しいワークスペースで手動で紐づけてください。

接続を解除する

設定 → コード の 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 を作成し、次の値を入力します。

Repository permissions:

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

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

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

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 のミラー、タスクの自動紐づけ、マージ時のステータス変更は動作しますが、PR カードに CI やマージ状態は表示されません。

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

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

make migrate-up

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

よくある問題

• 接続ボタンを使用できない: 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 のマージ後もタスクのステータスが変わらない: タスクの Pull requests リストの下にある説明を確認します。まだマージされていない PR やマージされずにクローズされた PR、またはこのタスクが PR マージでステータスを変えない設定であることが表示されます。説明がない場合は、ワークスペースが 変更しない に設定されているか、タスクがすでに変更先のステータスです。

次のステップ

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