Jiraイシューのインテグレーション

プラン: Free、Premium、Ultimate
提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

Jiraイシューのインテグレーションは、1つ以上のGitLabプロジェクトをJiraインスタンスに接続します。Jiraインスタンスは、自分でホストすることも、Jira Cloudでホストすることもできます。サポートされているJiraのバージョンは、6.x、7.x、8.x、9.x、10.xです。

インテグレーションを設定する

GitLab 16.0で、Jiraパーソナルアクセストークンによる認証が導入されました。
Jiraイシューセクションと脆弱性に関するJiraイシューセクションは、GitLab 16.10でjira_multiple_project_keysフラグとともに導入されました。デフォルトでは無効になっています。
Jiraイシューセクションと脆弱性に関するJiraイシューセクションは、GitLab 17.0で一般提供になりました。機能フラグjira_multiple_project_keysは削除されました。
GitLab 17.0で、Jiraイシューを有効にするチェックボックスがJiraイシューの表示に名称変更されました。
GitLab 17.0で、脆弱性からJiraイシューの作成を有効にするチェックボックスが脆弱性のJiraイシューを作成するに名称変更されました。
GitLab 17.5で、Jiraイシューのカスタマイズ設定が導入されました。
GitLab 19.0でJira Cloud service account認証が導入されました。

前提条件:

GitLabインストールでは、相対URLを使用できません。
Jira Cloudの場合:
- クラシックな（スコープなしの）APIトークンでBasic authenticationを使用するには、Jira Cloud API tokenと、そのトークンの作成に使用したメールアドレスが必要です。
- スコープ付きAPIトークンでBasic authenticationを使用するには、ユーザーアカウント用にスコープ付きトークンを作成し、Jira API URLをJira Platform API gateway (https://api.atlassian.com/ex/jira/{cloudId}) に設定する必要があります。詳細については、AtlassianアカウントのAPIトークンを管理するを参照してください。
- Jira Cloud service accountを使用するには、Jira Cloudサービスアカウントと、そのサービスアカウント用のスコープ付きAPIトークンが必要です。詳細については、サービスアカウントのAPIトークンを管理するを参照してください。
- IP許可リストを有効にしている場合は、GitLab.com IP範囲を許可リストに追加して、GitLabでJiraイシューを表示します。
Jira Data CenterまたはJira Serverの場合、次のいずれかが必要です。
- Jiraのユーザー名とパスワード。
- Jiraパーソナルアクセストークン（GitLab 16.0以降）。

GitLabのプロジェクト設定を構成することで、Jiraイシューのインテグレーションを有効にできます。また、GitLab Self-Managedでは、特定のグループまたはインスタンス全体のインテグレーションを設定することもできます。

このインテグレーションにより、GitLabプロジェクトは、インスタンス上のすべてのJiraプロジェクトとやり取りできるようになります。GitLabでプロジェクト設定を構成するには、次の手順に従います。

上部のバーで、検索または移動先を選択して、プロジェクトを見つけます。
左サイドバーで、設定 > インテグレーションを選択します。
Jiraのイシューを選択します。
インテグレーションを有効にするで、有効チェックボックスをオンにします。
認証方法で、次のいずれかを選択します:
- Basic authentication: Jira Cloudの場合はメールとAPIトークン、Jira Data CenterまたはJira Serverの場合はユーザー名とパスワードを使用します。
  - メールアドレスまたはユーザー名:
    - Jira Cloudの場合は、メールアドレスを入力します。
    - Jira Data CenterまたはJira Serverの場合は、ユーザー名を入力します。
  - APIトークンまたはパスワード:
    - Jira Cloudの場合は、APIトークンを入力します。
    - Jira Data CenterまたはJira Serverの場合は、パスワードを入力します。
- パーソナルアクセストークン (Jira Data CenterおよびJira Serverのみ): Jiraパーソナルアクセストークンを入力します。
- Jira Cloud service account (Jira Cloudのみ):
  - Service account token: Jira Cloudサービスアカウント用のスコープ付きAPIトークンを入力します。
  - GitLabがアクセスするJiraプロジェクトに対して、サービスアカウントが十分な権限を持っていることを確認してください。
接続の詳細を入力します。
- Web URL: このGitLabプロジェクトにリンクするJiraインスタンスのWebインターフェースのベースURL (例: https://jira.example.comまたはhttps://example.atlassian.net)。
- Jira API URL: JiraインスタンスAPIのベースURL。設定されていない場合、Web URLの値が使用されます。
  - クラシックな（スコープなしの）APIトークンを使用するJira Cloudの場合は、このフィールドを空白のままにします。
  - スコープ付きAPIトークン（ユーザーアカウントまたはサービスアカウント）を使用するJira Cloudの場合は、Jira Platform API gateway: https://api.atlassian.com/ex/jira/{cloudId}を入力します。Cloud IDを見つけるには、Atlassianの指示を参照してください。
トリガー設定を指定します。
- コミットとマージリクエストのいずれか、または両方をトリガーとして選択します。GitLabでJiraイシューIDをメンションすると、GitLabはそのイシューにリンクします。
- GitLabにリンクバックするJiraイシューにコメントを追加するには、コメントを有効にするチェックボックスをオンにします。
- GitLabでJiraイシューを自動的に移行するには、Jiraトランジションを有効にするチェックボックスをオンにします。
Jiraイシューの一致セクションで、次のことを行います。
- Jiraイシューの正規表現に、正規表現パターンを入力します。
- Jiraイシューの接頭辞に、プレフィックスを入力します。
（オプション）GitLabでJiraイシューを表示するには、Jiraイシューセクションで、次の手順を実行します。
1. Jiraイシューの表示チェックボックスをオンにします。
  お使いのGitLabプロジェクトにアクセスできるすべてのユーザーは、認証するために使用されたAPIトークンがアクセスできるすべてのJiraイシューを表示できます。以下に入力するJiraプロジェクトキーは、GitLabに表示されるイシューリストをフィルターします。これらはAPIトークンのアクセスを制限しません。インテグレーションが読み取ることができるイシューを制限するには、公開したいJiraプロジェクトのみにアクセスできるJiraアカウントを使用し、そのアカウントからAPIトークンを生成します。
2. 1つ以上のJiraプロジェクトキーを表示するために入力します。APIトークンがアクセスできるすべてのキーを表示するには、空白のままにします。
（オプション）脆弱性に関するJiraイシューを作成するには、脆弱性に関するJiraイシューセクションで、次の手順を実行します。
1. 脆弱性のJiraイシューを作成するチェックボックスをオンにします。
  この設定は、個々のプロジェクトとグループに対してのみ有効にできます。
2. Jiraプロジェクトキーを入力します。
3. このプロジェクトキーのイシューのタイプを取得（）を選択してから、作成するJiraイシューのタイプを選択します。
4. （オプション）Jiraイシューのカスタマイズチェックボックスをオンにして、脆弱性に対して作成されたJiraイシューの詳細を確認、変更、または追加できるようにします。
（オプション）テスト設定を選択します。
変更を保存を選択します。

Jiraイシューを表示する

プラン: Premium、Ultimate

グループのJiraイシューを有効にする機能は、GitLab 16.9で導入されました。
複数のJiraプロジェクトからイシューを表示する機能は、GitLab 16.10でjira_multiple_project_keysフラグとともに導入されました。デフォルトでは無効になっています。
複数のJiraプロジェクトからイシューを表示する機能は、GitLab 17.0で一般提供になりました。機能フラグjira_multiple_project_keysは削除されました。

前提条件:

Jiraイシューのインテグレーションが設定され、Jiraイシューの表示チェックボックスがオンになっていることを確認してください。

Jiraイシューは、特定のグループまたはプロジェクトに対して有効にできますが、GitLabプロジェクト内でのみイシューを表示できます。GitLabプロジェクト内で1つ以上のJiraプロジェクトのイシューを表示するには、次の手順に従います。

上部のバーで、検索または移動先を選択して、プロジェクトを見つけます。
左サイドバーで、Plan > JIRAイシューを選択します。

デフォルトでは、イシューは作成日でソートされます。最近作成されたイシューが上部に表示されます。イシューを絞り込んで、イシューを選択すると、GitLabでそのイシューを表示できます。

イシューは、Jiraステータスに基づいて、次のタブにグループ化されます。

オープン: Jiraステータスが完了以外のイシュー。
クローズ: Jiraステータスが完了のイシュー。
すべて: あらゆるJiraステータスのイシュー。

Jiraイシューを絞り込む

プラン: Premium、Ultimate

前提条件:

Jiraイシューのインテグレーションが設定され、Jiraイシューの表示チェックボックスがオンになっていることを確認してください。

GitLabでJiraイシューを表示するときに、サマリーと説明のテキストでイシューを絞り込むことができます。次の条件でイシューを絞り込むこともできます。

ラベル: URLのlabels[]パラメータで、1つ以上のJiraイシューラベルを指定します。複数のラベルを指定すると、指定されたすべてのラベルを持つイシューのみが表示されます（例: /-/integrations/jira/issues?labels[]=backend&labels[]=feature&labels[]=QA）。
ステータス: URLのstatusパラメータでJiraイシューのステータスを指定します（例: /-/integrations/jira/issues?status=In Progress）。
レポーター: URLのauthor_usernameパラメータでJira表示名を指定します（例: /-/integrations/jira/issues?author_username=John Smith）。
担当者: URLのassignee_usernameパラメータでJira表示名を指定します（例: /-/integrations/jira/issues?assignee_username=John Smith）。
プロジェクト: URLのprojectパラメータのJiraプロジェクトキーを指定します（例: /-/integrations/jira/issues?project=GTL）。

Jira検証

プラン: Premium、Ultimate

前提条件:

Jiraイシューのインテグレーションが設定され、Jiraイシューの表示チェックボックスがオンになっていることを確認してください。

コミットメッセージで参照されるJiraイシューが、プッシュを許可する前に特定の基準を満たしていることを保証するために、検証ルールを設定できます。この機能は、GitLabとJira間で一貫したワークフローを維持するのに役立ちます。

GitLabが検証チェックを実行する場合:

コミットメッセージに複数のJiraイシューキーが含まれている場合、最初のキーのみが検証チェックに使用されます。
既知のイシューにより、イシューが存在するかの確認設定をクリアしてもチェックは停止しません。チェックの実行を停止する唯一の方法は、すべてのJira検証チェックをクリアすることです。

Jira検証を構成するには:

上部のバーで、検索または移動先を選択して、プロジェクトを見つけます。
左サイドバーで、設定 > インテグレーションを選択します。
Jiraのイシューを選択します。
Jira検証セクションに移動します。
次の検証チェックを構成します:
- イシューが存在するかの確認: コミットメッセージで参照されるJiraイシューがJiraに存在することを検証します。
- 担当者の確認: コミットメッセージで参照されるJiraイシューの担当者がコミッターであることを検証します。
- イシューのステータスの確認: コミットメッセージで参照されるJiraイシューが、許可されたステータスのいずれかであることを検証します。
- 許可された状態: 許可されたJiraイシューステータスのコンマ区切りリスト (例: Ready, In Progress, Review)。このフィールドは、イシューのステータスの確認が有効になっている場合にのみ使用できます。
変更を保存を選択します。

ユーザーが検証基準を満たさない変更をプッシュしようとすると、GitLabはプッシュが拒否された理由を示すエラーメッセージを表示します。

エラーメッセージの例

参照されたJiraイシューが存在しない場合 (イシューが存在するかの確認が有効な場合):
```
Jira issue PROJECT-123 does not exist.
```
参照されたJiraイシューがコミッターに割り当てられていない場合 (担当者の確認が有効な場合):
```
Jira issue PROJECT-123 is not assigned to you. It is assigned to Jane Doe.
```
参照されたJiraイシューのステータスが許可されたリストにない場合 (イシューのステータスの確認が有効な場合):
```
Jira issue PROJECT-123 has status 'Done', which is not in the list of allowed statuses: Ready, In Progress, Review.
```

検証チェックのユースケース

次の例を検討してください。

あなたのチームは、Jiraイシューが積極的に作業されているときに特定のステータスにあるべきワークフローを使用しています。
Jira検証を次のように構成します:
- イシューが存在するか確認します。
- イシューが「In Progress」または「レビュー」ステータスであることを検証します。
あるデベロッパーが、コミットメッセージ「修正PROJECT-123 by adding検証」で変更をプッシュしようとします。
GitLabは以下を確認します:
- JiraイシューPROJECT-123が存在する。
- イシューのステータスが「In Progress」または「レビュー」である。
すべてのチェックが合格した場合、プッシュが許可されます。いずれかのチェックが失敗した場合、プッシュはエラーメッセージとともに拒否されます。

これにより、対応するJiraイシューが適切な状態にないときにコード変更がプッシュされるのを防ぐことで、チームが正しいワークフローに従うことを保証します。

脆弱性のJiraイシューを作成する

プラン: Ultimate

前提条件:

Jiraイシューのインテグレーションが設定され、脆弱性のJiraイシューを作成するチェックボックスがオンになっていることを確認してください。
ターゲットプロジェクトでイシューを作成する権限があるJiraユーザーアカウントが必要です。

GitLabからJiraイシューを作成して、脆弱性の解決または軽減のために講じられたアクションを追跡できます。脆弱性のJiraイシューを作成するには、次の手順に従います。

上部のバーで、検索または移動先を選択して、プロジェクトを見つけます。
左サイドバーで、セキュリティ > 脆弱性レポートを選択します。
脆弱性の説明を選択します。
Jiraイシューを作成を選択します。
Jiraイシューのカスタマイズ設定が選択されている場合は、Jiraインスタンスのイシュー作成フォームにリダイレクトされます。このフォームには、脆弱性データが事前に入力されています。Jiraイシューを作成する前に、詳細を確認、変更、追加できます。

イシューは、脆弱性レポートからの情報をもとに、ターゲットJiraプロジェクトに作成されます。

GitLabイシューを作成するには、脆弱性に対するGitLabイシューを作成するを参照してください。

Jira Cloud APIトークンを作成する

Jira CloudのJiraイシューインテグレーションを構成するには、APIトークンが必要です。

ユーザーアカウントの場合

Jiraプロジェクトへの書き込みアクセス権があるアカウントからAtlassianにサインインします。
リンクをクリックすると、APIトークンページが開きます。または、Atlassianプロファイルから、Account Settings > セキュリティ > Create and manage API tokensを選択します。
APIトークンを作成するを選択します。
ダイアログで、トークンのラベルを入力し、作成を選択します。
APIトークンをコピーするには、コピーを選択します。

サービスアカウントの場合

Jira Cloudサービスアカウントを作成または識別します。詳細については、Atlassianサービスアカウントのドキュメントを参照してください。
サービスアカウント用のスコープ付きAPIトークンを作成します。詳細については、サービスアカウントのAPIトークンを管理するを参照してください。
トークンに少なくとも次のクラシックなJiraスコープがあることを確認してください:
- read:jira-user
- read:jira-work
- write:jira-work

Jiraサイト間で移行する

GitLabでJiraサイト間の移行を行い、Jiraイシューのインテグレーションを維持するには、次の手順に従います。

インテグレーションの設定の手順に従います。
新しいJiraサイトのURLを入力します（例: https://myjirasite.atlassian.net）。

GitLab 18.6以降では、既存のJiraイシュー参照は新しいJiraサイトURLを使用するように自動的に更新されます。

GitLab 18.5以前では、既存のJiraイシュー参照を更新するためにMarkdownキャッシュを無効にする必要があります。