mirror of
https://github.com/multica-ai/multica.git
synced 2026-08-08 11:53:43 +02:00
e395fb8744
Complete rework of the docs site, in three passes squashed into one change: 1. P0 fact corrections across the core-loop pages (agent access model, comment triggers and coalescing, issue lifecycle, offline/queue semantics, task states and retries, dispatch via realtime push). 2. Chinese rewrite as the authoring language: final 12-group IA, new "Core concepts" and "Put agents to work" pages, curated welcome page, permanent-UI quickstart (no onboarding-wizard dependency), operator reference restored (CLI command reference, webhook response codes, task state/timeout tables, config set keys, upgrade notes). 3. Verification and sync: every load-bearing claim re-checked against current main with file:line evidence (migration 103 auto-backfill, CLI-only trigger toggling, duplication semantics, COOKIE_DOMAIN, GitHub App variables, Qwen Code as the 17th provider); register standards applied to all 39 pages; en/ja/ko synced from zh with same-language heading anchors (verified, zero dead links); 17 product screenshots plus 2 diagrams wired in. Supporting fixes: i18n middleware no longer swallows /images assets, sidebar folder indent survives custom link padding, unused editorial components removed. Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
186 lines
12 KiB
Plaintext
186 lines
12 KiB
Plaintext
---
|
|
title: GitHub 連携
|
|
description: pull request を Multica のイシューに紐づけ、開発の進捗をイシューから確認します。
|
|
---
|
|
|
|
import { Callout } from "fumadocs-ui/components/callout";
|
|
|
|
GitHub を接続すると、Multica はイシュー番号を使って pull request を自動的に紐づけます。イシューの詳細画面から、PR の状態、変更規模、CI の結果、マージ競合を直接確認できます。
|
|
|
|
GitHub 連携が読み取るのは、インストール時に許可されたリポジトリだけです。コード、コメント、status check を書き込むことはありません。
|
|
|
|
セルフホスト版 Multica では、セルフホストの Forgejo、Gitea、GitLab インスタンスも同時に接続できます。PR の自動紐づけ、マージ時の Done への変更、CI 表示を同じように利用できます。**設定 → 連携 → Git ホスティング**から設定してください。詳しくは[セルフホスト Git ホスティング](/vcs-integration)を参照してください。Multica Cloud にはこの項目はありません。
|
|
|
|
## GitHub を接続する
|
|
|
|
ワークスペースの owner または admin が接続できます。
|
|
|
|
1. **設定 → GitHub** を開きます。
|
|
2. GitHub 連携のメインスイッチを有効にします。
|
|
3. **GitHub に接続**をクリックします。
|
|
4. GitHub でアカウントまたは organization を選び、すべてのリポジトリか指定したリポジトリを許可します。
|
|
5. インストールが完了したら Multica に戻ります。
|
|
|
|
接続状態は同じページに表示されます。通常のメンバーは状態を確認できますが、接続、切断、スイッチの変更はできません。
|
|
|
|
<Callout type="info">
|
|
**GitHub 接続**は、Multica がどのリポジトリから PR イベントを受け取るかを決めます。**コードリポジトリ**設定は、エージェントがタスクを実行するときに選べるリポジトリを決めます。用途が異なるため、それぞれ設定する必要があります。
|
|
</Callout>
|
|
|
|
## 機能スイッチ
|
|
|
|
**設定 → GitHub** には 4 つのスイッチがあります。
|
|
|
|
| スイッチ | 機能 |
|
|
|---|---|
|
|
| GitHub 連携 | メインスイッチ。無効にすると下の 3 項目は機能しなくなりますが、GitHub App の接続は解除されません。 |
|
|
| PR サイドバー | 紐づいた pull request をイシューの詳細画面に表示します。 |
|
|
| Co-authored-by | エージェントが作成する commit に `Co-authored-by: multica-agent <github@multica.ai>` を追加します。 |
|
|
| PR の自動紐づけ | PR のブランチ名、タイトル、本文からイシュー番号を検出します。 |
|
|
| **PR カード → CI とマージ可否** | 紐づいた各 PR について、Multica は認証済みの GitHub API スナップショットを取得し、その **CI ステータス**と**マージ可否**をカードにミラーリングします（下記の **PR カードに表示される内容** を参照）。 |
|
|
|
|
|
|
## PR をイシューに紐づける
|
|
|
|
最も簡単な方法は、イシュー番号をブランチ名または PR タイトルへ入れることです。イシューが `MUL-123` の場合:
|
|
|
|
```text
|
|
mul-123-fix-login-redirect
|
|
```
|
|
|
|
```text
|
|
MUL-123 ログイン後のリダイレクトを修正
|
|
```
|
|
|
|
Multica は大文字と小文字を区別せず、現在のワークスペースのイシュー接頭辞だけを照合します。1 つの PR を複数のイシューに紐づけることもできます。
|
|
|
|
イシュー番号を PR 本文だけに書く場合は、GitHub の closing keyword を使ってください。
|
|
|
|
```text
|
|
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` に変更するのは、次の条件をすべて満たす場合だけです。
|
|
|
|
1. 紐づいたマージ済み PR のうち少なくとも 1 つで、`Closes MUL-123` のように closing keyword の直後にイシュー番号を指定している。`Closes login MUL-123` のように間に別の単語がある形式は無効です。
|
|
2. そのイシューに、`Open` または `Draft` の作業 PR がほかに残っていない。本文中の通常の参照は作業 PR に含みません。
|
|
3. イシューの現在の状態が `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 |
|
|
| 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 の権限、および関連イベントの購読を省略できます。
|
|
|
|
<Callout type="warning">
|
|
必要なのは **Webhook secret** であり、OAuth Client secret ではありません。GitHub と Multica に入力した Webhook secret が異なる場合、GitHub delivery は `401 invalid signature` を返します。
|
|
</Callout>
|
|
|
|
### 2. 環境変数を設定する
|
|
|
|
App の公開 URL から slug を確認します。たとえば `https://github.com/apps/multica-acme` の slug は `multica-acme` です。
|
|
|
|
```dotenv
|
|
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 として認証し、スナップショットを取得します。
|
|
|
|
```dotenv
|
|
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. データベースを更新して接続する
|
|
|
|
既存のデプロイをアップグレードする場合は、通常のデータベースマイグレーションを先に実行します。
|
|
|
|
```bash
|
|
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 に Checks と Commit statuses の read-only 権限があり、関連イベントを購読していることを確認します。インストール済み App に権限を追加した場合は、各 installation の所有者が GitHub 上で承認するまで有効になりません。
|
|
- **PR のマージ後もイシューが完了しない**: PR で closing keyword を使っていることと、`Open` または `Draft` の関連 PR がほかに残っていないことを確認します。
|
|
|
|
## 次のステップ
|
|
|
|
- [イシュー](/issues) — 状態遷移と PR マージによる Done への変更
|
|
- [プロジェクトリソース](/project-resources) — エージェントが実行時に使えるリポジトリ
|
|
- [環境変数](/environment-variables) — セルフホスト GitHub App の全設定
|