mirror of
https://gh-proxy.org/https://github.com/klinsmaya/multica.git
synced 2026-11-09 01:46:46 +08:00
Bohan Jiang
116761e505
A bare body mention of an issue key claimed nothing, yet auto-link wrote a link row for it and flagged it reference_only — filtered out of the PR list, the close aggregate and the review dedup head SHA. The row had no reader, and once the PR went terminal the preserve gate froze the flag, so adding `Closes MUL-1` to a merged PR's body could never surface the PR on its issue. With no unlink surface anywhere, the one repair available from GitHub was the one that could not work. Write no row for a passing mention, delete the historical hidden rows (migration 458), and drop the column's reads and writes; the column itself goes in a follow-up release that re-runs the delete as a mop-up. The visible set of links is unchanged, except that a post-merge `Closes` now links the PR (without retroactively completing the issue). An open PR whose claim is downgraded in place loses its link, which is what hiding used to accomplish. Docs, the four locales, and the agent-facing platform skill are updated in step.
187 lines
13 KiB
Plaintext
187 lines
13 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 <[email protected]>` を追加します。 |
|
|
| PR の自動紐づけ | PR のブランチ名とタイトルからタスク番号を検出します。本文では closing keyword の直後にある番号だけを検出します。 |
|
|
| **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` のような通常の参照を書いただけでは、そのタスクへまったく紐づきません。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 がほかに残っていない。
|
|
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 |
|
|
| 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 カードからマージ状態も消えます。
|
|
|
|
<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 に Contents、Checks、Commit statuses の read-only 権限があり、関連イベントを購読していることを確認します。Contents が欠けるとスナップショット全体が失敗し、PR カードには CI もマージ状態も表示されません。インストール済み App に権限を追加した場合は、各 installation の所有者が GitHub 上で承認するまで有効になりません。
|
|
- **PR のマージ後もタスクが完了しない**: PR で closing keyword を使っていることと、`Open` または `Draft` の関連 PR がほかに残っていないことを確認します。
|
|
|
|
## 次のステップ
|
|
|
|
- [タスク](/issues) — 状態遷移と PR マージによる Done への変更
|
|
- [プロジェクトリソース](/project-resources) — エージェントが実行時に使えるリポジトリ
|
|
- [環境変数](/environment-variables) — セルフホスト GitHub App の全設定
|