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

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

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

前提要件:

• GitLabインストールでは、相対URLを使用できません。
• Jira Cloudの場合:
  • Jira Cloud 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でプロジェクト設定を構成するには、次の手順に従います:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。
2. 設定 > インテグレーションを選択します。
3. JIRAイシューを選択します。
4. インテグレーションを有効にするで、有効チェックボックスをオンにします。
5. 接続の詳細を入力します:
   • Web URL: このGitLabプロジェクトにリンクするJiraインスタンスWebインターフェースのベースURL（例: https://jira.example.com）。
   • JIRA APIのURL: JiraインスタンスAPIのベースURL（例: https://jira-api.example.com）。このURLが設定されていない場合、Web URLの値がデフォルトで使用されます。Jira Cloudの場合は、JIRA APIのURLを空白のままにします。
   • 認証方法:
     • Basic:
       • メールアドレスまたはユーザー名:
         • Jira Cloudの場合は、メールアドレスを入力します。
         • Jira Data CenterまたはJira Serverの場合は、ユーザー名を入力します。
       • APIトークンまたはパスワード:
         • Jira Cloudの場合は、APIトークンを入力します。
         • Jira Data CenterまたはJira Serverの場合は、パスワードを入力します。
     • Jiraパーソナルアクセストークン: パーソナルアクセストークンを入力します。
6. トリガー設定を指定します:
   • コミットとマージリクエストのいずれか、または両方をトリガーとして選択します。GitLabでJiraイシューIDをメンションすると、GitLabはそのイシューにリンクします。
   • GitLabにリンクバックするJiraイシューにコメントを追加するには、コメントを有効にするチェックボックスをオンにします。
   • GitLabでJiraイシューを自動的に移行するには、Jiraトランジションを有効にするチェックボックスをオンにします。
7. Jiraイシューの一致セクションで、次のことを行います:
   • Jiraイシューの正規表現に、正規表現パターンを入力します。
   • Jiraイシューの接頭辞に、プレフィックスを入力します。
8. オプション。GitLabでJiraイシューを表示するには、JIRAイシューセクションで、次の手順を実行します:

   1. Jiraイシューの表示チェックボックスをオンにします。

      この設定を有効にすると、GitLabプロジェクトへのアクセス権を持つすべてのユーザーが、指定したJiraプロジェクトからすべてのイシューを表示できるようになります。

   2. 1つ以上のJiraプロジェクトキーを入力します。利用可能なすべてのキーを含めるには、空白のままにします。

9. オプション。脆弱性に関するJiraイシューを作成するには、Jira issues for vulnerabilities（脆弱性に関するJiraイシュー）セクションで、次の手順を実行します:

   1. 脆弱性のJiraイシューを作成するチェックボックスをオンにします。

      この設定は、個別のプロジェクトとグループに対してのみ有効にできます。

   2. Jiraプロジェクトキーを入力します。

   3. このプロジェクトキーのイシューのタイプを取得（ ）を選択してから、作成するJiraイシューのタイプを選択します。

   4. オプション。Jiraイシューのカスタマイズチェックボックスをオンにして、脆弱性に対して作成されたJiraイシューの詳細を確認、変更、または追加できるようにします。

10. オプション。テスト設定を選択します。
11. 変更を保存を選択します。

Jiraイシューを表示する

前提要件:

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

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

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

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

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

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

Jiraイシューを絞り込む

前提要件:

• 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検証

前提要件:

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

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

Jira検証を設定するには、次の手順に従います:

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

ユーザーが検証基準を満たさない変更をプッシュしようとすると、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.

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

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

1. あなたのチームは、Jiraイシューが積極的に作業されている場合、特定の状態にあるべきワークフローを使用します。
2. Jira検証を次のように設定します:
   • イシューが存在することを確認します
   • イシューが「In Progress」または「Review」状態になっていることを検証します
3. デベロッパーがコミットメッセージ「検証を追加してPROJECT-123を修正する」で変更をプッシュしようとします。
4. GitLabは以下を確認します:
   • JiraイシューPROJECT-123が存在すること
   • このイシューの状態が「In Progress」または「Review」のいずれかであること
5. すべてのチェックに合格した場合、プッシュは許可されます。いずれかのチェックが失敗した場合、エラーメッセージが表示されてプッシュは拒否されます。

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

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

前提要件:

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

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

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。

2. セキュリティ > 脆弱性レポートを選択します。

3. 脆弱性の説明を選択します。

4. Jiraイシューを作成を選択します。

   Jiraイシューのカスタマイズ設定が選択されている場合は、Jiraインスタンスのイシュー作成フォームにリダイレクトされます。このフォームには、脆弱性データが事前に入力されています。Jiraイシューを作成する前に、詳細を確認、変更、追加できます。

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

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

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

Jira CloudのJiraイシューのインテグレーションを設定するには、Jira Cloud APIトークンが必要です。Jira Cloud APIトークンを作成するには、次の手順に従います:

1. Jiraプロジェクトへの書き込みアクセス権があるアカウントからAtlassianにサインインします。

   リンクをクリックすると、API tokens（APIトークン）ページが開きます。または、Atlassianプロファイルから、Account Settings（アカウント設定） > Security（セキュリティ） > Create and manage API tokens（APIトークンの作成と管理）を選択します。

2. Create API token（APIトークンを作成する）を選択します。

3. ダイアログで、トークンのラベルを入力し、作成を選択します。

APIトークンをコピーするには、コピーを選択します。

Jiraサイト間で移行する

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

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

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

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