mirror of
https://gh-proxy.org/https://github.com/klinsmaya/multica.git
synced 2026-11-10 02:16:45 +08:00
104bf7be35
* feat(mcp): report how many agents use each workspace MCP server The workspace MCP library listing now carries agent_count: the number of live (non-archived) agents each entry is assigned to. Settings shows it so an admin can tell whether replacing or removing a server affects anyone. The field is optional in the client schema, so an older server that omits it simply shows no count. Co-Authored-By: Claude Opus 5.5 <[email protected]> Co-authored-by: multica-agent <[email protected]> * feat(settings): regroup settings by scope and consolidate scattered pages Implements the MUL-7732 settings redesign: - Navigation is grouped by who a setting affects: Personal, the current workspace (with Issues & workflow and Connections & extensions sub-groups), and This device on desktop. Pages and sections carry a scope badge (account, this device, workspace), and members see a lock on pages only owners and admins can change plus a shared read-only notice. - Settings search in the nav indexes page and row titles and descriptions; opening a result scrolls to and highlights the row. - Preferences is one page instead of three tabs, with a searchable time zone picker, a segmented theme control and a field grid for the create-issue dialogs. - Code merges Repositories, GitHub and self-hosted Git. Repositories are read-only rows edited through dialogs; self-hosted Git connects in a dialog that ends on the one-time webhook secret. - The PR merge rule moves to Statuses & transitions as an automatic transition; Code only shows its current value. Built-in statuses show edit and archive as unavailable instead of refusing after a click. - Integrations becomes Messaging (IM channels only) with a breadcrumb on detail pages; Composio moves to Personal as Connected apps. - Members gets tabs, search, invite and share-link dialogs and a seat summary. MCP servers show assignment counts and explain how MCP, connected apps and plugins differ. Workspace General shows members plain values and changes the issue prefix through an explicit dialog. - Skill labels are managed from the Skills page; Settings > Labels keeps the issue catalog. - Successful saves no longer toast; failures still do. Old ?tab= values (github, repositories, integrations, issue, chat, labs, and the Composio OAuth callback) resolve to the new pages, since server redirects still use them. Co-Authored-By: Claude Opus 5.5 <[email protected]> Co-authored-by: multica-agent <[email protected]> * docs: point settings paths at the regrouped settings pages GitHub, repositories and self-hosted Git now live under Settings > Code, IM bots under Settings > Messaging, and the PR merge rule under Settings > Statuses & transitions. The GitHub guide also drops the old master switch step in favor of pausing from the GitHub row. Co-Authored-By: Claude Opus 5.5 <[email protected]> Co-authored-by: multica-agent <[email protected]> * fix(settings): edit the PR merge rule on the Code page The "After PRs merge, move the issue to" rule sits with the other pull request rules on Code again instead of a separate Automatic transitions section. It applies to every code host, so pausing GitHub features does not lock it. The statuses page goes back to Issue Statuses, and its merge badge links to the rule on Code. Co-Authored-By: Claude Opus 5.5 <[email protected]> Co-authored-by: multica-agent <[email protected]> * fix(settings): manage skill labels under Settings → Labels again The Skills page entry was buried at the bottom of the filter menu's Labels submenu. Settings → Labels switches between the issue and skill catalogs again, using the members page's segmented switch (now SettingsViewTabs), and the Skills page keeps its shortcut. Co-Authored-By: Claude Opus 5.5 <[email protected]> Co-authored-by: multica-agent <[email protected]> * fix(settings): keep GitHub resume reachable after a disconnect Pausing GitHub features is a workspace setting, but the pause and resume item lived in a menu that only rendered with an installation. A workspace paused before disconnecting, or with github_enabled=false and no installation, lost the way back, and every PR switch stayed disabled. On deployments without a GitHub App it could not even reconnect, though Co-authored-by works without one. The menu now shows whenever GitHub is connected or paused, and only Disconnect requires an installation. The paused note shows in either state. Co-Authored-By: Claude Opus 5.5 <[email protected]> Co-authored-by: multica-agent <[email protected]> * fix(settings): let the URL choose the open members list The members page read `section` only to initialize its list tab, so a search result for invitations or share links opened while already on the page changed the URL but not the list, and back/forward did nothing. With a router the open list is now derived from the URL, and switching lists replaces `section`. Co-Authored-By: Claude Opus 5.5 <[email protected]> Co-authored-by: multica-agent <[email protected]> * fix(settings): tell repositories on different ports apart The manual repository dialog reused the GitHub import's identity, which drops the port, so https://git.example.com:9443/acme/api.git read as a duplicate of the same path on :8443 and could not be saved. Non-default ports now stay in the identity; default ports, including 22 for ssh://, still compare equal to the scp-like form. Co-Authored-By: Claude Opus 5.5 <[email protected]> Co-authored-by: multica-agent <[email protected]> * test(comments): stop the recipient-menu tests flaking under CI load The steering tests opened a recipient chip menu while the composer could still re-render its chips, from the previous send settling or the preview catching up. That closed the menu, and the menu steps also used the 1s default wait inside the 5s default test timeout. Under parallel load locally, about 1 in 20 runs failed the same way as CI. Menu choices now go through a helper that reopens the menu until the item shows. The remaining waits get the 5s the first steps already had, and each test gets 15s. 140 of 140 loaded runs pass. Co-Authored-By: Claude Opus 5.5 <[email protected]> Co-authored-by: multica-agent <[email protected]> --------- Co-authored-by: Claude Opus 5.5 <[email protected]> Co-authored-by: multica-agent <[email protected]>
195 lines
16 KiB
Plaintext
195 lines
16 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 の自動紐づけ、マージ時のステータス変更、CI 表示を同じように利用できます。**設定 → コード**から設定してください。詳しくは[セルフホスト Git ホスティング](/vcs-integration)を参照してください。Multica Cloud にはこの項目はありません。
|
|
|
|
## GitHub を接続する
|
|
|
|
ワークスペースの owner または admin が接続できます。
|
|
|
|
1. **設定 → コード** を開きます。
|
|
2. **GitHub** の行で **GitHub に接続**をクリックします。
|
|
3. GitHub でアカウントまたは organization を選び、すべてのリポジトリか指定したリポジトリを許可します。
|
|
4. インストールが完了したら Multica に戻ります。
|
|
|
|
接続状態は同じページに表示されます。通常のメンバーは状態を確認できますが、接続、切断、スイッチの変更はできません。
|
|
|
|
<Callout type="info">
|
|
**GitHub 接続**は、Multica がどのリポジトリから PR イベントを受け取るかを決めます。**コードリポジトリ**設定は、エージェントが作業を実行するときに選べるリポジトリを決めます。用途が異なるため、それぞれ設定する必要があります。
|
|
</Callout>
|
|
|
|
## 機能スイッチ
|
|
|
|
**設定 → コード** の **プルリクエストとタスク** には次の設定があります。GitHub の行の **⋯** メニューで **GitHub 機能を一時停止** すると、下の 3 項目は機能しなくなりますが、GitHub App の接続は解除されません。
|
|
|
|
| 設定 | 機能 |
|
|
|---|---|
|
|
| PR サイドバー | 紐づいた pull request をタスクの詳細画面に表示します。 |
|
|
| Co-authored-by | エージェントが作成する commit に `Co-authored-by: multica-agent <[email protected]>` を追加します。 |
|
|
| PR の自動紐づけ | ブランチ名かタイトルにタスク番号を含む PR、または本文で closing keyword の直後にタスク番号を置いた PR を、そのタスクに紐づけます。 |
|
|
| PR マージ後のタスクのステータス | タスクに紐づく PR がすべてマージされたとき、タスクをあるステータス（既定は `Done`）に変更するか、変更しないかを選びます。下記の **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` のような通常の参照を書いただけでは、そのタスクへまったく紐づきません。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 ホスティング](/vcs-integration)を含むすべてのコードホストで共通です。
|
|
|
|
## 複数のワークスペース
|
|
|
|
同じ 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 を作成し、次の値を入力します。
|
|
|
|
| フィールド | 値 |
|
|
|---|---|
|
|
| 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 のミラー、タスクの自動紐づけ、マージ時のステータス変更は動作しますが、PR カードに CI やマージ状態は表示されません。
|
|
|
|
### 3. データベースを更新して接続する
|
|
|
|
既存のデプロイをアップグレードする場合は、通常のデータベースマイグレーションを先に実行します。
|
|
|
|
```bash
|
|
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 マージでステータスを変えない設定であることが表示されます。説明がない場合は、ワークスペースが **変更しない** に設定されているか、タスクがすでに変更先のステータスです。
|
|
|
|
## 次のステップ
|
|
|
|
- [タスク](/issues) — 状態遷移と PR マージの関係
|
|
- [プロジェクトリソース](/project-resources) — エージェントが実行時に使えるリポジトリ
|
|
- [環境変数](/environment-variables) — セルフホスト GitHub App の全設定
|