セルフホスト Git ホスティング

ワークスペースごとにセルフホストの Forgejo、Gitea、GitLab インスタンスを接続し、イシュー番号を参照する Pull Request / Merge Request を対応するイシューへ自動的に紐づけ、マージ時に「完了」へ移動して CI ステータスを表示します。

セルフホスト版 Multica 専用です。 この連携は Multica を自分でデプロイしている場合のみ利用でき、Multica Cloud では提供されません。ここでの「セルフホスト」は Multica 自体のセルフホストを意味します。通常は独自ネットワーク内の Git インスタンスへアクセスするために使用します。サーバー運用者が MULTICA_VCS_INTEGRATION_ENABLED=true を設定して機能を有効にし、MULTICA_VCS_SECRET_KEY も設定する必要があります。それまでは、設定 → 連携にこのセクションは表示されません。

Multica はワークスペースごとにセルフホストの Git ホスティング、Forgejo、Gitea、GitLab のいずれかへ接続します。接続後、ブランチ名、タイトル、本文にイシュー番号（例: MUL-123）を含む Pull Request（GitLab では Merge Request）は、対応するイシューへ自動的に紐づけられ、イシューサイドバーの Pull requests に表示されます。終了キーワードを含む PR がマージされると、イシューは「完了」へ移動します。head commit の CI はカード上のチェックバーとして表示されます。

これらの Git ホスティングは GitHub と並行して利用でき、1 つのワークスペースで任意に組み合わせられます。

GitHub と異なり、これらの Git ホスティングには「App」モデルがありません。各ワークスペースが独自のインスタンス URL とアクセストークンを保存し、リポジトリまたは組織へ Webhook を登録します。トークンと Webhook secret はどちらも暗号化して保存されます。

前提条件（サーバー）

まず、このデプロイで連携を有効にします。デフォルトでは無効であり、有効にするまでセクションは表示されません。

MULTICA_VCS_INTEGRATION_ENABLED=true

公式のセルフホスト用 docker compose ファイル（docker-compose.selfhost.yml）では設定済みです。

次に、保存する認証情報をサーバーが暗号化するための、base64 でエンコードした 32 バイトの鍵を設定します。設定しない場合、接続フォームは利用できません。

openssl rand -base64 32

MULTICA_VCS_SECRET_KEY=<base64 32 バイト鍵>

両方が必要です。スイッチは機能を提供するかどうかを決め、鍵は保存するトークンと Webhook secret を暗号化します。接続、Webhook、ローテーションはいずれも両方の設定を必要とします。

MULTICA_PUBLIC_URL にサーバーの公開ベース URL を設定すると、Multica がそのまま貼り付けられる Webhook URL を表示できます。設定しない場合、画面には Webhook のパスだけが表示されるため、origin を自分で補います。

ワークスペースを接続

Git ホスティング側で、リポジトリの読み取り権限を持つアクセストークンを作成します。
- Forgejo / Gitea: 設定 → アプリケーション。
- GitLab: read_api 権限を持つ個人（またはグループ/プロジェクト）アクセストークン。
Multica で 設定 → 連携 → Git ホスティングを開きます。
プロバイダーを選択し、インスタンス URL（例: https://forgejo.example.com）とアクセストークンを入力して接続をクリックします。Multica は保存前に、そのトークンでインスタンスへアクセスして検証します。
接続後に表示される Webhook URL と Webhook secret をコピーします。

Webhook secret は一度しか表示されません。ページを離れる前にコピーしてください。同じインスタンスへ再接続すると、トークンと secret がローテーションされます。

Webhook を登録

リポジトリ（または全リポジトリを対象にする組織/グループ）で設定します。

Forgejo / Gitea — 設定 → Webhook → Webhook を追加 → Forgejo/Gitea:

送信先 URL: 前の手順で取得した Webhook URL。
HTTP メソッド POST、コンテンツタイプ application/json。
secret: Webhook secret（X-Gitea-Signature HMAC の検証に使用）。
トリガーイベント: Pull Request を選び、CI をミラーするには Commit Status も選択。

GitLab — 設定 → Webhooks:

URL: Webhook URL。
Secret token: Webhook secret（X-Gitlab-Token として送信され、文字列をそのまま比較）。
トリガー: Merge request events を有効にし、CI をミラーするには Pipeline events も有効化。

Multica は保存済みの secret で各 delivery を検証するため、一致する secret がない Webhook は拒否されます。

ミラーされる内容

Pull / Merge Request — open、closed、merged、draft の状態、作成者、ブランチ、および Git ホスティングが提供する場合は diff 統計。
イシューの紐づけ — タイトル、本文、ブランチの番号で PR をイシューへ紐づけます。マージ済み PR に終了キーワード（Closes/Fixes/Resolves MUL-123）があり、open の関連 PR が残っていなければ、イシューを「完了」へ移動します。
CI — Forgejo/Gitea の commit status と GitLab pipeline を、head commit の成功/失敗/進行中チェックバーへ集約します。

エージェントによる Pull Request の作成

PR の作成には Multica 側の Git ホスティング設定は不要です。エージェントはランタイムでリポジトリを checkout し、ランタイムホスト自身の Git 認証情報を使ってブランチを push し、PR を作成します。エージェントを特定の Git ホスティングで動かすには、SSH deploy key やホストの Git credential helper に保存したトークンなどを使って、デーモンホストがその Git ホスティングへ認証できるようにし、通常どおりリポジトリ URL を追加してください。任意の Git URL を checkout できるため、プロバイダー固有の設定は必要ありません。