GitHub・GitLab 連携

リポジトリを連携して、Issue とタスク、マイルストーンとスプリントを双方向に同期し、lockfile・SBOM を push のたびに自動で取り込む方法。

プロジェクトに GitHub または GitLab（gitlab.com・セルフホスト）のリポジトリを連携すると、次のことが自動で行われます。

• Issue とタスクが双方向に同期されます（タイトル・状態・担当者・ラベル）
• マイルストーンとスプリントが対応付けられます
• プルリクエスト（マージリクエスト）がマージされると、そこで閉じた Issue のタスクが完了になります
• 自動で作られたセキュリティ対応タスクが Issue になります
• 既定ブランチへの push のたびと毎日 1 回、リポジトリの lockfile・SBOM を取り込みます

連携する

プロジェクトの「リポジトリ連携」タブで「リポジトリを連携」を押します。このタブはプロジェクトを管理できる人（プロジェクトのオーナー、会社管理者、部署長、グループ管理者）にだけ表示されます。

「連携する」を押すと、トークンでリポジトリを読めるか確かめてから保存します。そのあと、lockfile と開いている Issue・マイルストーンをバックグラウンドで取り込みます。

アクセストークンの権限

GitHub: Fine-grained personal access token（または GitHub App のトークン）で、対象リポジトリに次の権限を付けます。

GitLab: Project access token（またはグループ・個人のトークン）で api スコープを付けます。Webhook を自動で登録するには Maintainer 以上のロールが必要です。

トークンは暗号化して保存され、画面には二度と表示されません。期限が切れたときは「トークンを変更」から入れ直します。

Webhook

Webhook を通して、Issue の変更や push がすぐに Vectana に届きます。トークンに権限がなく自動で登録できなかった場合は、連携の画面に Webhook の URL とシークレットが表示されるので、手で登録してください。

Webhook の URL は、管理者が設定した Vectana の公開 URL（WEB_URL）から作られます。GitHub・GitLab から届く URL にしておいてください。

Webhook が届かなくても、毎日 1 回の取り込みと「Issue を取り込む」ボタンで追いつけます。

Issue とタスク

Vectana → GitHub / GitLab

連携したあとに作ったタスクは、Issue としても作られます。連携より前からあるタスクは Issue になりません（リポジトリが急に Issue で埋まらないようにするためです）。

タスクのタイトル・状態・優先度・種別・担当者・スプリントを変えると、Issue にも反映されます。

Issue の本文には、タスクの説明と Vectana のタスクへのリンクが入ります。Issue の文言は、リポジトリを連携した人の表示言語で書かれます。Issue に自分で付けたほかのラベルや、Vectana の知らないアサインはそのまま残ります。

見積時間・ポイント・期限・依存関係・進み具合など、Vectana だけの項目は Issue には送りません。

GitHub / GitLab → Vectana

Issue を作ったり変えたりすると、タスクに反映されます。

• 新しい Issue はタスクになります（「Issue とタスクを同期する」がオンのとき）
• タイトル・オープン/クローズ・ラベル（種別と優先度）・担当者・マイルストーンが反映されます
• 担当者は、アカウント名を登録している Vectana のユーザーに対応付けます。知らないアカウントだけがアサインされた場合は、タスクの担当者を変えません

タスクには Issue 番号のリンクが付き、ボードや一覧、タスクの画面から Issue を開けます。

プルリクエストのマージで完了

プルリクエスト（GitLab はマージリクエスト）のタイトルや説明に Closes #12・Fixes #12・Resolves #12 と書いておくと、マージしたときに Issue #12 のタスクが完了になります。

マイルストーンとスプリント

Vectana でスプリントを作ると、同じ名前のマイルストーンが作られます（すでに同じ名前のマイルストーンがあればそれを使います）。名前・終了日・ゴールの変更や、スプリントの完了も反映されます。

GitHub・GitLab で作ったマイルストーンは、計画中のスプリントになります。スプリントの完了は、ポイントの確定や未完了タスクの戻しを伴うので、Vectana で行ってください。

セキュリティ対応タスクの Issue

セキュリティ対応タスクが自動で作られると、Issue（ラベル security）も作られます。脆弱性がすべて解消してタスクが自動で完了すると、Issue もクローズされます。

Issue にしたくない場合は、連携の画面で「自動作成されたセキュリティ対応タスクを Issue にする」をオフにします。

lockfile・SBOM の取り込み

既定ブランチへの push のたびと、毎日 1 回、リポジトリにある lockfile・SBOM をパッケージとして取り込みます。「今すぐ取り込む」でいつでも取り込めます。

• 対応形式はパッケージの登録と同じです。node_modules/ や vendor/ の中は読みません
• 取り込み元は git:リポジトリ/パス（例: git:acme/portal/web/package-lock.json）になるので、ファイルごとに入れ替わります
• リポジトリから消えたファイルのパッケージは削除されます。別のファイルに移っただけのパッケージは、対応状況やタスクを残したまま引き継ぎます
• 1 回に読むのは最大 50 ファイルです

「取り込むファイル」に 1 行に 1 つパターンを書くと、そのファイルだけを読みます。* と ** が使えます。

web/package-lock.json
api/**
services/*/go.sum

CI から送る方法（CI から自動で登録する）も引き続き使えます。両方を使う場合は、同じファイルを二重に取り込まないよう、どちらかに寄せてください。

アカウント名の登録

Issue の担当者と Vectana のユーザーは、各自が「個人設定」の「GitHub・GitLab のアカウント」に登録したユーザー名で対応付けます。大文字・小文字は区別しません。

連携の解除

ゴミ箱で連携を解除します。Vectana が登録した Webhook は削除されます。タスクと Issue のリンク、取り込んだパッケージはそのまま残ります。

うまくいかないとき

最後のエラーが連携の画面に表示されます。