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

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

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

![リポジトリ連携](/screenshots/ja/project-repos.png)

## 連携する [#link]

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

| 項目 | 内容 |
| --- | --- |
| サービス | GitHub または GitLab |
| リポジトリ | GitHub は `owner/name`、GitLab は `group/project`（サブグループも可） |
| GitHub Enterprise Server / セルフホストの GitLab | チェックして URL を入力します。GitHub Enterprise は API の URL（`https://ホスト名/api/v3`）、GitLab はサーバの URL（`https://ホスト名`） |
| アクセストークン | 下の権限を持つトークン |
| Issue とタスクを同期する | オフにすると、lockfile の取り込みだけを行います |
| 自動作成されたセキュリティ対応タスクを Issue にする | 初期値はオン |
| Webhook を自動で登録する | 初期値はオン |
| 取り込むファイル | 空欄ならリポジトリ全体。指定方法は[取り込むファイル](#files)を参照 |

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

### アクセストークンの権限 [#token]

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

| 権限 | 用途 |
| --- | --- |
| Contents: Read | lockfile・SBOM の取り込み |
| Issues: Read and write | Issue・マイルストーンの同期 |
| Webhooks: Read and write | Webhook の自動登録（手で登録するなら不要） |

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

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

### Webhook [#webhook]

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

| サービス | 登録場所 | 設定 |
| --- | --- | --- |
| GitHub | リポジトリの Settings → Webhooks | Content type: `application/json`、Secret: 表示されたシークレット、イベント: Pushes・Issues・Milestones・Pull requests |
| GitLab | プロジェクトの設定 → Webhooks | シークレットトークン: 表示されたシークレット、トリガー: プッシュイベント・Issue イベント・マージリクエストイベント |

Webhook の URL は、管理者が設定した Vectana の公開 URL（[`WEB_URL`](/self-hosting/configuration)）から作られます。GitHub・GitLab から届く URL にしておいてください。

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

## Issue とタスク [#issues]

### Vectana → GitHub / GitLab

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

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

| Vectana | Issue |
| --- | --- |
| タイトル | タイトル（セキュリティ対応タスクは「lodash を 4.17.21 に更新」の形） |
| 状態「完了」 | クローズ。それ以外はオープン |
| 種別「セキュリティ対応」「その他」 | ラベル `security`・`other` |
| 優先度 | ラベル `priority: high`・`priority: medium`・`priority: low` |
| 担当者 | アサイン（[アカウント名](#accounts)を登録している人だけ） |
| スプリント | マイルストーン |

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

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

### GitHub / GitLab → Vectana

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

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

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

### プルリクエストのマージで完了 [#merge]

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

## マイルストーンとスプリント [#sprints]

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

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

## セキュリティ対応タスクの Issue [#security]

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

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

## lockfile・SBOM の取り込み [#files]

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

- 対応形式は[パッケージの登録](/guides/packages)と同じです。`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 から自動で登録する](/guides/ci)）も引き続き使えます。両方を使う場合は、同じファイルを二重に取り込まないよう、どちらかに寄せてください。

## アカウント名の登録 [#accounts]

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

## 連携の解除 [#unlink]

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

## うまくいかないとき [#troubleshooting]

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

| 表示 | 対処 |
| --- | --- |
| リポジトリを読み取れません: ... 401 | トークンの期限切れ・失効。「トークンを変更」で入れ直します |
| リポジトリを読み取れません: ... 404 | リポジトリ名の誤り、またはトークンにそのリポジトリの権限がない |
| Webhook not registered | Webhook の権限がない。表示された URL とシークレットで[手で登録](#webhook)します |
| 最後の通知が更新されない | Webhook が届いていない。GitHub・GitLab の Webhook の配信履歴を確認します |