セルフホスト 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）、または本文で終了キーワードの直後にタスク番号を置いた PR は、対応するタスクへ自動的に紐づけられ、タスクサイドバーの 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 がローテーションされます。

プライベート CA を使うインスタンス

接続で、プロバイダーの証明書が "is signed by a certificate authority this server does not trust" と表示された場合、インスタンスの HTTPS 証明書は Multica サーバーが信頼していない社内 CA で発行されている（または自己署名である）ということです。サーバー管理者がその CA をバックエンドの信頼ストアに追加してください。Helm では backend.extraCACerts.configMap を設定し、Docker Compose では CA をマウントして SSL_CERT_DIR を設定します。手順は Private CA certificates を参照してください。

接続リクエストにはアクセストークンが含まれるため、Multica には証明書の検証をスキップするオプションはありません。証明書がホスト名と一致しない、または検証に失敗した（例: 有効期限切れ）と表示された場合は、証明書そのものを修正してください。CA を信頼しても解決しません。

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（GitHub とセルフホストの両方）がすべてマージされると、GitHub と同じ設定とルールに従って、ワークスペースが選んだステータスへタスクを移動します。プロバイダーを接続すると、このページにも同じ 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 できるため、プロバイダー固有の設定は必要ありません。