GitLab for Jira Cloudアプリ

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

このページには、GitLab for Jira Cloudアプリのユーザードキュメントが含まれています。管理者向けドキュメントについては、GitLab for Jira Cloudアプリの管理を参照してください。

GitLab for Jira Cloudアプリを使用すると、GitLabとJira Cloudを接続して、開発情報をリアルタイムで同期できます。この情報は、Jira開発パネルで表示できます。

GitLab for Jira Cloudアプリを使用して、トップレベルグループまたはサブグループをリンクできます。プロジェクトやパーソナルネームスペースを直接リンクすることはできません。

GitLab.comでGitLab for Jira Cloudアプリを設定するには、GitLab for Jira Cloudアプリをインストールします。

アプリを設定した後、Atlassianが開発および管理しているプロジェクトツールチェーンを使用して、GitLabリポジトリをJiraプロジェクトにリンクできます。プロジェクトツールチェーンは、GitLabとJira Cloud間で開発情報を同期する方法には影響しません。

Jira Data CenterまたはJira Serverには、Atlassianが開発および管理しているJira DVCSコネクタを使用してください。

Jiraに同期されたGitLabデータ

グループをリンクした後、そのグループ内のすべてのプロジェクトでは、JiraのイシューIDをメンションした際に次のGitLabデータがJiraに同期されます。

既存のプロジェクトデータ（グループをリンクする前に作成）:
- 直近の400件のマージリクエスト
- 直近の400個のブランチと、それらの各ブランチへの最新のコミット（GitLab 15.11以降）
新しいプロジェクトデータ（グループをリンクした後に作成）:
- マージリクエスト
  - マージリクエスト作成者
- ブランチ
- コミット
  - コミット作成者
- パイプライン
- デプロイ
- 機能フラグ

GitLab for Jira Cloudアプリをインストールする

プラン: Free、Premium、Ultimate
提供形態: GitLab.com

前提条件:

ネットワークは、GitLabとJira間の受信接続と送信接続を許可する必要があります。
特定のJiraユーザー要件を満たしている必要があります。

GitLab for Jira Cloudアプリをインストールするには、次の手順に従います。

Jiraのトップバーで、Apps > Explore more appsを選択し、GitLab for Jira Cloudを検索してください。
GitLab for Jira Cloudを選択してから、Get it now（今すぐ入手）を選択します。

または、Atlassian Marketplaceからアプリを直接入手してください。

これで、GitLab for Jira Cloudアプリを設定できます。

概要については、Atlassian MarketplaceからGitLab for Jira CloudアプリをGitLab.comにインストールするを参照してください。

上記のビデオでは古いUniversal Plugin Managerインターフェースが表示されていますが、これは新しいJira Cloudインスタンスでは利用できない場合があります。次の手順は、古いアプリ管理インターフェースと新しいアプリ管理インターフェースの両方を対象としています。

GitLab for Jira Cloudアプリを設定する

プラン: Free、Premium、Ultimate
提供形態: GitLab.com

前提条件:

GitLabグループのメンテナーまたはオーナーロールが必要です。
特定のJiraユーザー要件を満たしている必要があります。

GitLab for Jira Cloudアプリを1つ以上のGitLabグループにリンクすることで、GitLabからJiraにデータを同期できます。GitLab for Jira Cloudアプリを設定するには、次の手順に従います。

Jiraで、Appsの横にある横の省略記号（）を選択し、Manage your appsを選択します。
次のいずれかの方法を使用してアプリに移動してください:
- 集中型アプリ管理を設定したインスタンスの場合:
  1. 「App management has moved to Administration」と表示された場合は、Take me thereを選択します。それ以外の場合は、For instances with legacy app managementの手順に従ってください。
  2. Installed appsタブで、GitLab for Jiraを見つけます。アプリのインストール方法に応じて、アプリの名前は次のようになります。
    - GitLab for Jira (gitlab.com): Atlassian Marketplaceからアプリをインストールした場合。
    - GitLab for Jira (<gitlab.example.com>): アプリを手動でインストールした場合。
  3. 横の省略記号（）を選択し、始めましょうを選択してインテグレーションを設定します。
- 従来のアプリ管理を設定したインスタンスの場合:
  1. GitLab for Jiraを展開します。アプリのインストール方法に応じて、アプリの名前は次のようになります。
    - GitLab for Jira (gitlab.com): Atlassian Marketplaceからアプリをインストールした場合。
    - GitLab for Jira (<gitlab.example.com>): アプリを手動でインストールした場合。
  2. 開始を選択して、インテグレーションを設定します。
（オプション）GitLab Self-ManagedをJiraにリンクするには、GitLabのバージョンを変更を選択します。
1. すべてのチェックボックスをオンにし、次へを選択します。
2. GitLabインスタンスのURLを入力し、保存を選択します。
GitLabにサインインを選択します。
エンタープライズユーザーで、グループのパスワード認証が無効になっている場合は、まずグループのシングルサインオンURLを使用してGitLabにサインインする必要があります。
GitLabはグループをリンクするためにサインインを求めますが、設定を特定のユーザーに紐付けません。GitLabインスタンスは、Jira内の情報を更新するために使用されるトークンをJiraから受け取ります。詳細については、GitLabからJiraへのアクセスを参照してください。
認証を選択します。これで、グループのリストが表示されるようになります。
グループをリンクを選択します。
グループにリンクするには、リンクを選択します。

GitLabグループにリンクした後:

そのグループ内のすべてのプロジェクトのデータがJiraに同期されます。初回のデータ同期は、1分あたり20プロジェクトのバッチで実行されます。プロジェクト数の多いグループでは、一部のプロジェクトのデータ同期が遅れる場合があります。
GitLab for Jira Cloudアプリのインテグレーションは、グループとそのグループ内のすべてのサブグループまたはプロジェクトに対して自動的に有効になります。このインテグレーションにより、Jira Service Managementを設定できるようになります。

Jira Service Managementを設定する

この機能はコミュニティのコントリビュートとして追加され、GitLabコミュニティのみによって開発および保守されています。

前提条件:

GitLab for Jira Cloudアプリをインストールしている必要があります。
GitLab for Jira Cloudアプリの設定でリンクするGitLabグループが存在する必要があります。

GitLabをITサービスプロジェクトに接続して、デプロイを追跡できます。

設定は、GitLabのGitLab for Jira Cloudアプリインテグレーションで行います。GitLabグループをリンクすると、そのグループ、サブグループ、およびプロジェクトに対してインテグレーションが有効になります。

GitLab for Jira Cloudアプリインテグレーションの有効化と無効化は、グループのリンクを通じて完全に自動的に行われ、GitLabインテグレーションフォームやAPIを介して操作することはできません。

Jira Service Managementで、次の手順を実行します。

サービスプロジェクトで、プロジェクトの設定 > Change managementに移動します。
Connect Pipeline > GitLabを選択し、セットアップフローの最後にサービスIDをコピーします。

GitLabで、次の手順を実行します。

上部のバーで、検索または移動先を選択して、プロジェクトを見つけます。
設定 > インテグレーションを選択します。
GitLab for Jira Cloudアプリを選択します。インテグレーションが無効になっている場合は、まずGitLabグループをリンクします。これにより、そのグループ、サブグループ、プロジェクトに対して、GitLab for Jira Cloudアプリインテグレーションが有効になります。
サービスIDフィールドに、このプロジェクトにマップするサービスIDを入力します。複数のサービスIDを使用する場合は、各サービスIDをカンマで区切ります。

最大100個のサービスをマップできます。

Jiraでのデプロイ追跡の詳細については、デプロイ追跡を設定するを参照してください。

GitLabでデプロイゲートを設定する

プラン: Premium、Ultimate
提供形態: GitLab.com

この機能はコミュニティのコントリビュートとして追加され、GitLabコミュニティのみによって開発および保守されています。

デプロイゲートを設定して、GitLabの変更リクエストの承認を得るためにJira Service Managementに送信できます。デプロイゲートを使用すると、指定した環境へのGitLabのデプロイはすべてJira Service Managementに自動的に送信され、承認された場合にのみデプロイされます。

サービスアカウントトークンを作成する

GitLabでサービスアカウントトークンを作成するには、まずパーソナルアクセストークンを作成する必要があります。このトークンは、Jira Service ManagementでGitLabのデプロイを管理するために使用されるサービスアカウントトークンを認証します。

サービスアカウントトークンを作成するには、次の手順に従います。

サービスアカウントユーザーを作成します。
パーソナルアクセストークンを使用して、サービスアカウントをグループまたはプロジェクトに追加します。
サービスアカウントを保護環境に追加します。
パーソナルアクセストークンを使用して、サービスアカウントトークンを生成します。
サービスアカウントトークンの値をコピーします。

デプロイゲートを有効にする

デプロイゲートを有効にするには、次の手順に従います。

GitLabで、次の手順を実行します。
1. 上部のバーで、検索または移動先を選択して、プロジェクトを見つけます。
2. 設定 > インテグレーションを選択します。
3. GitLab for Jira Cloudアプリを選択します。
4. デプロイゲートで、デプロイゲートを有効にするチェックボックスをオンにします。
5. 環境ティアテキストボックスに、デプロイゲートを有効にする環境の名前を入力します。複数の環境名を入力する場合は、カンマで区切ります（例: production, staging, testing, development）。小文字のみを使用してください。
6. 変更を保存を選択します。
Jira Service Managementで、次の手順を実行します。
1. デプロイゲートを設定します。
2. Service account token（サービスアカウントトークン）テキストボックスに、GitLabからコピーしたサービスアカウントトークンの値を貼り付けます。

サービスアカウントを保護環境に追加する

GitLabの保護環境にサービスアカウントを追加するには、次の手順に従います。

上部のバーで、検索または移動先を選択して、プロジェクトを見つけます。
設定 > CI/CDを選択します。
保護環境を展開し、環境を保護を選択します。
環境を選択ドロップダウンリストから、保護する環境を選択します（例: ステージング）。
デプロイ許可ドロップダウンリストから、この環境にデプロイできるユーザーを選択します（例: デベロッパー + メンテナー）。
承認者ドロップダウンリストから、作成したサービスアカウントを選択します。
保護を選択します。

APIリクエストの例

サービスアカウントユーザーを作成します。

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "name=<name_of_your_choice>&username=<username_of_your_choice>"  "<https://gitlab.com/api/v4/groups/<group_id>/service_accounts"

パーソナルアクセストークンを使用して、サービスアカウントをグループまたはプロジェクトに追加します。

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     --data "user_id=<service_account_id>&access_level=30" "https://gitlab.com/api/v4/groups/<group_id>/members"
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     --data "user_id=<service_account_id>&access_level=30" "https://gitlab.com/api/v4/projects/<project_id>/members"

パーソナルアクセストークンを使用して、サービスアカウントトークンを生成します。

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"
"https://gitlab.com/api/v4/groups/<group_id>/service_accounts/<service_account_id>/personal_access_tokens" --data "scopes[]=api,read_user,read_repository" --data "name=service_accounts_token"

GitLab for Jira Cloudアプリを更新する

アプリのほとんどの更新は自動的に行われます。詳細については、Atlassianのドキュメントを参照してください。

アプリに追加の権限が必要な場合は、Jiraで更新を手動で承認する必要があります。

セキュリティに関する考慮事項

GitLab for Jira Cloudアプリは、GitLabとJiraを接続します。データは2つのアプリケーション間で共有する必要があり、双方向でアクセスを許可する必要があります。

GitLabからJiraへのアクセス

GitLab for Jira Cloudアプリを設定すると、GitLabはJiraから共有シークレットトークンを受け取ります。このトークンは、Jiraプロジェクトに対するREAD、WRITE、DELETEアプリスコープをGitLabに付与します。これらのスコープは、Jiraプロジェクトの開発パネル内の情報を更新するために必要です。このトークンは、アプリがインストールされているJiraプロジェクト以外のAtlassian製品に対して、GitLabのアクセスを許可するものではありません。

このトークンはAES256-GCMで暗号化され、GitLabに保存されます。JiraプロジェクトからGitLab for Jira Cloudアプリがアンインストールされると、GitLabはトークンを削除します。

JiraからGitLabへのアクセス

Jiraは、GitLabへのアクセス権を取得しません。

GitLabからJiraに送信されるデータ

Jiraに送信されるすべてのデータについては、Jiraに同期されたGitLabデータを参照してください。

Jiraに送信される特定のデータプロパティの詳細については、データ同期に関係するシリアライザークラスを参照してください。

JiraからGitLabに送信されるデータ

GitLab for Jira Cloudアプリがインストールまたはアンインストールされると、GitLabはJiraからライフサイクルイベントを受信します。イベントには、後続のライフサイクルイベントを検証したり、Jiraにデータを送信する際に認証したりするためのトークンが含まれています。Jiraからのライフサイクルイベントリクエストは検証されます。

Atlassian MarketplaceのGitLab for Jira Cloudアプリを使用するGitLab Self-Managedインスタンスの場合、GitLab.comがライフサイクルイベントを処理し、GitLab Self-Managedインスタンスに転送します。詳細については、GitLab.comにおけるアプリのライフサイクルイベントの処理を参照してください。

Jiraによって保存されるデータ

Jiraに送信されたデータは、Jiraによって保存され、Jira開発パネルに表示されます。

GitLab for Jira Cloudアプリがアンインストールされると、Jiraはこのデータを完全に削除します。このプロセスは非同期で行われ、数時間かかる場合があります。

Atlassian Marketplaceのプライバシーとセキュリティの詳細

詳細については、Atlassian Marketplaceリストのプライバシーとセキュリティの詳細を参照してください。

トラブルシューティング

GitLab for Jira Cloudアプリを操作する際に、次の問題が発生する可能性があります。

管理者向けドキュメントについては、GitLab for Jira Cloudアプリの管理を参照してください。

エラー: `Failed to link group`

GitLab for Jira Cloudアプリを接続する際に、次のエラーが発生する場合があります。

Failed to link group. Please try again.

権限が不十分でJiraからユーザー情報を取得できない場合、403 Forbiddenが返されます。

この問題を解決するには、特定のJiraユーザー要件を満たしていることを確認してください。

GitLabグループにリンクした後、Jiraコードが動作しない

GitLab for Jira CloudアプリをGitLabグループにリンクした後、Jiraコードが動作しない場合があります。この問題を解決するには、BitbucketとJiraの両方を設定する必要があります。

Bitbucketの設定:

Atlassianアカウントにサインインします。
ワークスペースを作成し、名前を入力します。

Jiraの設定:

Projects（プロジェクト）で、対象プロジェクトを選択します。
開発 > コードを選択します。
Connect Bitbucket > Link Bitbucket Cloud workspaceを選択します。
Bitbucketで作成したワークスペースを選択します。
Grant access（アクセスを許可）を選択します。

これで、リポジトリがJiraコードに表示されます。

詳細については、イシューJRACLOUD-95847を参照してください。

GitLab for Jira Cloudアプリ

Jiraに同期されたGitLabデータ

GitLab for Jira Cloudアプリをインストールする

GitLab for Jira Cloudアプリを設定する

Jira Service Managementを設定する

GitLabでデプロイゲートを設定する

サービスアカウントトークンを作成する

デプロイゲートを有効にする

サービスアカウントを保護環境に追加する

APIリクエストの例

GitLab for Jira Cloudアプリを更新する

セキュリティに関する考慮事項

GitLabからJiraへのアクセス

JiraからGitLabへのアクセス

GitLabからJiraに送信されるデータ

JiraからGitLabに送信されるデータ

Jiraによって保存されるデータ

Atlassian Marketplaceのプライバシーとセキュリティの詳細

トラブルシューティング

エラー: Failed to link group

GitLabグループにリンクした後、Jiraコードが動作しない

エラー: `Failed to link group`