GitLab for Jira Cloudアプリの管理

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

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

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

GitLab Self-ManagedインスタンスでGitLab for Jira Cloudアプリをセットアップするには、次のいずれかを実行します:

Atlassian MarketplaceからGitLab for Jira Cloudアプリをインストールする（GitLab 15.7以降）。
GitLab for Jira Cloudアプリを手動でインストールする。

概要については、以下を参照してください:

上記のビデオは、以前のUniversal Plugin Managerインターフェースを示していますが、これは新しいJira Cloudインスタンスでは利用できない可能性があります。以下の手順では、新旧両方のアプリ管理インターフェースについて説明します。

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

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

OAuth認証をセットアップする

GitLab for Jira Cloudアプリのインストール方法がAtlassian Marketplace経由か手動かにかかわらず、OAuthアプリケーションを作成する必要があります。

GitLab Self-ManagedインスタンスでOAuthアプリケーションを作成するには、次の手順に従います:

左側のサイドバーの下部で、管理者を選択します。新しいナビゲーションをオンにしている場合は、右上隅で自分のアバターを選択し、管理者を選択します。
アプリケーションを選択します。
New application（新しいアプリケーション）を選択します。
Redirect URI（リダイレクトURI）を次のように設定します:
- 公式のAtlassian Marketplaceリスティングからアプリをインストールする場合: https://gitlab.com/-/jira_connect/oauth_callbacks。
- アプリを手動でインストールする場合（<instance_url>はインスタンスのURLに置き換えます）: <instance_url>/-/jira_connect/oauth_callbacks。
信用済みチェックボックスと非公開チェックボックスをオフにします。
エラーを回避するため、これらのチェックボックスをオフにする必要があります。
スコープで、apiチェックボックスのみをオンにします。
アプリケーションを保存を選択します。
アプリケーションIDの値をコピーします。
左側のサイドバーで、設定 > 一般を選択します。
GitLab for Jira Appを展開します。
アプリケーションIDの値をJira接続アプリケーションIDに貼り付けます。
変更を保存を選択します。

Jiraのユーザー要件

Atlassian組織で、GitLab for Jira Cloudアプリのセットアップに使用するJiraユーザーが、次のいずれかのグループに属していることを確認する必要があります:

組織管理者（org-admins）グループ: 最近作成されたAtlassian組織は一元化されたユーザー管理を使用しており、これにはorg-adminsグループが含まれています。既存のAtlassian組織も、この一元化されたユーザー管理に移行中です。org-adminsグループが利用可能な場合は、このグループを使用して、GitLab for Jira Cloudアプリを管理できるJiraユーザーを指定する必要があります。または、site-adminsグループを使用することもできます。
サイト管理者（site-admins）グループ: site-adminsグループは、元のユーザー管理で使用されていました。

必要に応じて、次の操作を行います:

必要なグループを作成します。
グループを編集して、Jiraユーザーをグループのメンバーとして追加します。
Jiraでグローバル権限をカスタマイズしている場合は、Browse users and groups権限をJiraユーザーに付与する必要が生じる場合もあります。

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

Atlassian Marketplaceにある公式GitLab for Jira Cloudアプリは、GitLab Self-Managedインスタンスで使用できます。

この方法の概要は次のとおりです:

GitLab.comが、Jira Cloudから送信されるインストールとアンインストールのライフサイクルイベントを処理し、それをGitLabインスタンスに転送します。GitLab Self-Managedインスタンスからのすべてのデータは、引き続きJira Cloudに直接送信されます。
GitLab.comは、ブランチ作成リンクをインスタンスにリダイレクトすることで処理します。
GitLabのバージョンが17.2より前の場合、GitLab Self-ManagedインスタンスでJira Cloudからブランチを作成することはできません。詳細については、イシュー391432を参照してください。

または、次のような場合は、GitLab for Jira Cloudアプリを手動でインストールすることもできます:

インスタンスが前提要件を満たしていない。
公式のAtlassian Marketplaceリスティングからインストールしたくない。
GitLab.comにアプリのライフサイクルイベントを処理させたり、インスタンスへのアプリのインストールに関する情報をGitLab.comと共有したりすることを望まない。
GitLab.comにブランチ作成リンクをインスタンスにリダイレクトさせたくない。

前提要件

インスタンスを公開している必要があります。
インスタンスは、GitLabバージョン15.7以降である必要があります。
OAuth認証をセットアップする必要があります。
GitLabインスタンスはHTTPSを使用する必要があります。さらに、GitLabの証明書が公的に信頼されているか、完全なチェーン証明書を含んでいる必要があります。
ネットワーク設定では、以下を許可する必要があります:
- GitLab Self-ManagedインスタンスからJira Cloudへの送信接続（AtlassianのIPアドレス）
- GitLab Self-ManagedインスタンスとGitLab.com間の受信および送信接続（GitLab.comのIPアドレス）
- ファイアウォールの内側にあるインスタンスの場合:
  1. GitLab Self-Managedインスタンスの前面に、インターネットに接続されたリバースプロキシをセットアップします。
  2. GitLab.com（GitLab.comのIPアドレス）からの受信接続を許可するようにリバースプロキシを設定します。
  3. GitLab Self-Managedインスタンスが上記の送信接続を依然として確立できることを確認します。
アプリをインストールおよび設定するJiraユーザーは、特定の要件を満たしている必要があります。

Atlassian Marketplaceインストールのためにインスタンスをセットアップする

前提要件

GitLab 15.7以降でAtlassian MarketplaceインストールのためにGitLab Self-Managedインスタンスをセットアップするには、次の手順に従います:

左側のサイドバーの下部で、管理者を選択します。新しいナビゲーションをオンにしている場合は、右上隅で自分のアバターを選択し、管理者を選択します。
設定 > 一般を選択します。
GitLab for Jira Appを展開します。
Jira ConnectのプロキシURLにhttps://gitlab.comと入力して、Atlassian Marketplaceからアプリをインストールします。
変更を保存を選択します。

インスタンスをリンクする

前提要件

GitLab Self-ManagedインスタンスをGitLab for Jira Cloudアプリにリンクするには、次の手順に従います:

GitLab for Jira Cloudアプリをインストールします。
GitLab for Jira Cloudアプリを設定します。
（オプション）Jira Cloudがリンクされているかを確認します。

Jira Cloudがリンクされているかを確認する

Railsコンソールを使用して、Jira Cloudが以下にリンクされているかを確認できます:

特定のグループ:

JiraConnectSubscription.where(namespace: Namespace.by_path('group/subgroup'))

特定のプロジェクト:

Project.find_by_full_path('path/to/project').jira_subscription_exists?

任意のグループ:

installation = JiraConnectInstallation.find_by_base_url("https://customer_name.atlassian.net")
installation.subscriptions

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

GitLab 17.5以前では、GitLab for Jira Cloudアプリを手動でインストールする際に問題が発生する可能性があります。詳細については、イシュー505372を参照してください。この問題は、Atlassian Marketplaceからのインストールには影響しません。

公式のAtlassian Marketplaceリスティングからインストールしたくない場合は、GitLab for Jira Cloudアプリを手動でインストールしてください。

各Jira Cloudアプリは、1つの場所からインストールする必要があります。Jiraは、指定された場所からマニフェストファイルをフェッチします。マニフェストファイルは、アプリに関する情報をシステムに提供します。

GitLab Self-ManagedインスタンスをJira Cloudでサポートするには、次のいずれかを実行します:

アプリを開発モードでインストールする。
Atlassian Marketplaceリスティングを作成する。

前提要件

インスタンスを公開している必要があります。
OAuth認証をセットアップする必要があります。
ネットワーク設定では、以下を許可する必要があります:
- GitLab Self-ManagedインスタンスとJira Cloud間の受信および送信接続（AtlassianのIPアドレス）。
- ファイアウォールの内側にあるインスタンスの場合:
  1. GitLab Self-Managedインスタンスの前面に、インターネットに接続されたリバースプロキシをセットアップします。
  2. Jira Cloud（AtlassianのIPアドレス）からの受信接続を許可するようにリバースプロキシを設定します。
  3. GitLab Self-Managedインスタンスが上記の送信接続を依然として確立できることを確認します。
アプリをインストールおよび設定するJiraユーザーは、特定の要件を満たしている必要があります。

手動インストールのためにインスタンスをセットアップする

前提要件

GitLab 15.7以降で手動インストールのためにGitLab Self-Managedインスタンスをセットアップするには、次の手順に従います:

左側のサイドバーの下部で、管理者を選択します。新しいナビゲーションをオンにしている場合は、右上隅で自分のアバターを選択し、管理者を選択します。
設定 > 一般を選択します。
GitLab for Jira Appを展開します。
アプリを手動でインストールするには、Jira ConnectのプロキシURLを空白のままにします。
変更を保存を選択します。

アプリを開発モードでインストールする

前提要件

Atlassian Marketplaceの外部からアプリをインストールできるようにJiraインスタンスを設定するには、次の手順に従います:

管理者としてJiraインスタンスにサインインします。
Jiraインスタンスで開発モードを有効にします。
管理者としてGitLabにサインインします。
Jiraで、Appsの横にある水平方向の省略記号（）を選択し、Manage your appsを選択します。
次のいずれかの方法で、JiraインスタンスからGitLabをインストールします:
For instances with centralized app management:（集中アプリ管理インスタンスの場合：）
1. 「アプリ管理が[管理]に移動しました」と表示された場合は、Take me there（ここに移動）を選択します。それ以外の場合は、下記のFor instances with legacy app management（従来のアプリ管理インスタンスの手順）に従ってください。
2. Install a private app（プライベートアプリをインストール）を選択します。
3. Choose a product to install this app on（このアプリをインストールする製品を選択）ドロップダウンリストで、Jiraを選択します。
4. App descriptor URL（アプリ記述子URL）で、インスタンス設定に基づいて、マニフェストファイルの完全なURLを指定します。
  デフォルトでは、マニフェストファイルは/-/jira_connect/app_descriptor.jsonにあります。たとえば、インスタンスドメインがapp.pet-store.cloudの場合、マニフェストファイルはhttps://app.pet-store.cloud/-/jira_connect/app_descriptor.jsonにあります。
5. Install app（アプリをインストール）を選択します。
6. ページを更新します。
7. **GitLab for Jira (<gitlab.example.com>)**というアプリを見つけ、水平方向の省略記号（）を選択し、始めましょうを選択してGitLab for Jira Cloudアプリを設定します。
For instances with legacy app management:（従来のアプリ管理インスタンスの場合：）
1. Upload app（アプリをアップロード）を選択します。
2. App descriptor URL（アプリ記述子URL）で、インスタンス設定に基づいて、マニフェストファイルの完全なURLを指定します。
  デフォルトでは、マニフェストファイルは/-/jira_connect/app_descriptor.jsonにあります。たとえば、インスタンスドメインがapp.pet-store.cloudの場合、マニフェストファイルはhttps://app.pet-store.cloud/-/jira_connect/app_descriptor.jsonにあります。
3. アップロードを選択します。
4. **GitLab for Jira (<gitlab.example.com>)**というアプリを見つけ、シェブロン（）を選択し、始めましょうを選択してGitLab for Jira Cloudアプリを設定します。
Jiraインスタンスで開発モードを無効にします。

GitLabのアップグレードによりアプリ記述子が変更された場合は、アプリを再インストールする必要があります。

Atlassian Marketplaceリスティングを作成する

前提要件

開発モードを使用したくない場合は、独自のAtlassian Marketplaceリスティングを作成できます。これにより、Atlassian MarketplaceからGitLab for Jira Cloudアプリをインストールできます。

Atlassian Marketplaceリスティングを作成するには、次の手順に従います:

Atlassian Marketplaceのベンダーとして登録します。
アプリ記述子URLを使用してアプリケーションのリスティングを作成します。
- マニフェストファイルはhttps://your.domain/your-path/-/jira_connect/app_descriptor.jsonにあります。
- 公開アプリケーションはすべてのユーザーが閲覧およびインストールできるため、このリスティングではアプリケーションをprivateに設定する必要があります。
アプリケーションのテストライセンストークンを生成します。

GitLab.comマーケットプレースのリスティングと同様に、この方法は自動更新を使用します。

Atlassian Marketplaceリスティングの作成の詳細については、Atlassianのドキュメントを参照してください。

複数のGitLabインスタンスを接続する

GitLab for Jiraアプリを使用すると、複数のGitLabインスタンスを単一のJira Cloudインスタンスに接続できます。インストール方法は、接続するインスタンスによって異なります。

前提要件:

各インスタンスには、個別のOAuth認証が必要です。
各インストール方法の前提条件を満たしている必要があります。

GitLab.com + GitLab Self-Managedの場合:

GitLab.comの場合: Atlassian Marketplaceインストールを使用します。
GitLab Self-Managedインスタンスの場合: アプリを手動でインストールします。

複数のGitLabセルフマネージドインスタンスの場合:

最初のインスタンスでは、次のいずれかを行います: Atlassian Marketplaceインストールを使用するか、アプリを手動でインストールします。
他のインスタンスの場合: アプリを手動でインストールします。

Jira Cloudには、インストールごとにGitLab for Jiraアプリが表示されます。

組織ごとに1つのGitLabインスタンスのみが、公式のAtlassian Marketplaceリストを使用できます。

プロキシとして機能するようにGitLabインスタンスを設定する

ほとんどのユーザーにとって、この構成は必要ありません。複数のインスタンスを持つJira Cloudの場合、GitLab for Jiraアプリを使用して各インスタンスを接続できます。

GitLabインスタンスは、GitLab for Jira Cloudアプリを通じて他のGitLabインスタンスのプロキシとして機能できます。複数のGitLabインスタンスを管理していてもアプリの手動インストールを一度だけで済ませたい場合は、プロキシを使用することをおすすめします。

プロキシとして機能するようにGitLabインスタンスを設定するには、次の手順に従います:

左側のサイドバーの下部で、管理者を選択します。新しいナビゲーションをオンにしている場合は、右上隅で自分のアバターを選択し、管理者を選択します。
設定 > 一般を選択します。
GitLab for Jira Appを展開します。
公開キーのストレージを有効にするを選択します。
変更を保存を選択します。
GitLab for Jira Cloudアプリを手動でインストールする。

プロキシを使用する他のGitLabインスタンスでは、プロキシインスタンスを指すように次の設定を変更する必要があります:

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

次のセキュリティに関する考慮事項は、アプリの管理に固有のものです。アプリの使用に関する考慮事項については、セキュリティに関する考慮事項を参照してください。

GitLab.comにおけるアプリのライフサイクルイベントの処理

Atlassian MarketplaceからGitLab for Jira Cloudアプリをインストールすると、GitLab.comはJiraからライフサイクルイベントを受信します。これらのイベントは、アプリがJiraプロジェクトにインストールされたとき、またはJiraプロジェクトからアプリがアンインストールされたときに限定されます。

インストールイベントでは、GitLab.comはJiraからsecret token（シークレットトークン）を受信します。GitLab.comは、後でJiraからの受信ライフサイクルイベントを検証するため、AES256-GCMで暗号化されたこのトークンを保存します。

GitLab.comは、インスタンスが同じトークンでJiraへのリクエストを認証できるように、このトークンをGitLab Self-Managedインスタンスに転送します。GitLab Self-Managedインスタンスにも、GitLab for Jira Cloudアプリがインストールまたはアンインストールされたことが通知されます。

GitLab Self-ManagedインスタンスからJira開発パネルにデータを送信する場合、GitLab Self-ManagedインスタンスはJiraに直接データを送信し、GitLab.comには送信しません。GitLab.comがそのトークンを使用してJiraプロジェクトのデータにアクセスすることはありません。GitLab Self-Managedインスタンスが、そのトークンを使用してデータにアクセスします。

GitLab.comが受信するライフサイクルイベントとペイロードの詳細については、Atlassianのドキュメントを参照してください。

sequenceDiagram
accTitle: Dataflow of the GitLab for Jira Cloud app installed from the Atlassian Marketplace
accDescr: How GitLab.com handles lifecycle events when the GitLab for Jira Cloud app was installed from the Atlassian Marketplace

    participant Jira
    participant Your instance
    participant GitLab.com
    Jira->>+GitLab.com: App install/uninstall event
    GitLab.com->>-Your instance: App install/uninstall event
    Your instance->>Jira: Your development data

GitLab.comにおけるブランチ作成の処理

Atlassian MarketplaceからGitLab for Jira Cloudアプリをインストールした場合、開発パネルからブランチを作成するリンクは、最初にユーザーをGitLab.comにリダイレクトします。

Jiraは、GitLab.comにJWTトークンを送信します。GitLab.comは、トークンを検証してリクエストを処理し、その後リクエストをGitLabインスタンスにリダイレクトします。

OAuthを使用してGitLabにアクセスする

GitLabは、Jiraとアクセストークンを共有しません。ただし、ユーザーはアプリを設定するためにOAuthを通じて認証する必要があります。

アクセストークンは、PKCE OAuthフローを通じて取得され、クライアント側でのみ保存されます。OAuthフローを初期化するアプリのフロントエンドはJavaScriptアプリケーションであり、Jiraのiframeを通じてGitLabから読み込まれます。

OAuthアプリケーションには、APIへの完全な読み取りおよび書き込みアクセスを許可するapiスコープが必要です。このアクセスには、すべてのグループとプロジェクト、コンテナレジストリ、パッケージレジストリへのアクセスが含まれます。ただし、GitLab for Jira Cloudアプリは、このアクセスを次の目的にのみ使用します:

リンク可能なグループを表示する。
グループをリンクする。

OAuthを通じたアクセスは、ユーザーがGitLab for Jira Cloudアプリを設定する間のみ必要です。詳細については、アクセストークンの有効期限を参照してください。

リバースプロキシを使用する

可能であれば、GitLab Self-Managedインスタンスの前面にリバースプロキシを配置することは避けてください。代わりに、パブリックIPアドレスを使用し、ファイアウォールでドメインを保護することをおすすめします。

インターネットから直接アクセスできないGitLab Self-Managedインスタンスで、GitLab for Jira Cloudアプリを使用するためにリバースプロキシを配置する必要がある場合は、次の点に注意してください:

Atlassian MarketplaceからGitLab for Jira Cloudアプリをインストールする際は、GitLabの内部FQDNとリバースプロキシのFQDNの両方にアクセスできるクライアントを使用してください。
GitLab for Jira Cloudアプリを手動でインストールする場合は、OAuth認証をセットアップする際に、Redirect URI（リダイレクトURI）にリバースプロキシのFQDNを使用してください。
リバースプロキシは、使用するインストール方法の前提要件を満たしている必要があります:
- GitLab for Jira Cloudアプリを接続するための前提要件。
- GitLab for Jira Cloudアプリを手動でインストールするための前提要件。
Jira開発パネルは、リバースプロキシFQDNではなく、GitLabの内部FQDNまたはGitLab.comにリンクする可能性があります。詳細については、イシュー434085を参照してください。
パブリックインターネット上でリバースプロキシを保護するには、AtlassianのIPアドレスからの受信トラフィックのみを許可します。
プロキシで書き換えまたはサブフィルターを使用する場合は、プロキシがgitlab-jira-connect-${host}アプリキーを書き換えたり置き換えたりしないようにしてください。そうしないと、Failed to link groupエラーが発生する可能性があります。
Jira開発パネルでブランチを作成を選択すると、GitLabの内部FQDNではなく、リバースプロキシFQDNにリダイレクトされます。

外部NGINX

このサーバーブロックは、Jira Cloudと連携するGitLab用リバースプロキシの設定例です:

server {
  listen *:80;
  server_name gitlab.mycompany.com;
  server_tokens off;
  location /.well-known/acme-challenge/ {
    root /var/www/;
  }
  location / {
    return 301 https://gitlab.mycompany.com:443$request_uri;
  }
}
server {
  listen *:443 ssl;
  server_tokens off;
  server_name gitlab.mycompany.com;
  ssl_certificate /etc/letsencrypt/live/gitlab.mycompany.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/gitlab.mycompany.com/privkey.pem;
  ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384';
  ssl_protocols  TLSv1.2 TLSv1.3;
  ssl_prefer_server_ciphers off;
  ssl_session_cache  shared:SSL:10m;
  ssl_session_tickets off;
  ssl_session_timeout  1d;
  access_log "/var/log/nginx/proxy_access.log";
  error_log "/var/log/nginx/proxy_error.log";
  location / {
    proxy_pass https://gitlab.internal;
    proxy_hide_header upgrade;
    proxy_set_header Host             gitlab.mycompany.com:443;
    proxy_set_header X-Real-IP        $remote_addr;
    proxy_set_header X-Forwarded-For  $proxy_add_x_forwarded_for;
  }
}

この例では、次のように設定します:

gitlab.mycompany.comをリバースプロキシのFQDNに、gitlab.internalをGitLabの内部FQDNに置き換えます。
ssl_certificateとssl_certificate_keyには有効な証明書を設定します（この例ではCertbotを使用しています）。
GitLabとJira Cloudが正常に接続できるように、HostプロキシヘッダーにはリバースプロキシのFQDNを設定します。

Jira CloudからGitLabに接続する際は、リバースプロキシのFQDNのみを使用する必要があります。GitLabへのアクセスには、引き続きGitLabの内部FQDNを使用してください。リバースプロキシのFQDNからGitLabにアクセスすると、GitLabが期待どおりに動作しない場合があります。詳細については、イシュー21319を参照してください。

追加のJWTオーディエンスを設定する

GitLabがJiraからJWTトークンを受信すると、GitLabはJWTのオーディエンスを確認してトークンを検証します。デフォルトでは、オーディエンスはGitLabの内部FQDNから派生します。

一部のリバースプロキシ設定では、リバースプロキシFQDNを追加のJWTオーディエンスとして設定する必要が生じる場合があります。追加のJWTオーディエンスを設定するには、次の手順に従います:

左側のサイドバーの下部で、管理者を選択します。新しいナビゲーションをオンにしている場合は、右上隅で自分のアバターを選択し、管理者を選択します。
設定 > 一般を選択します。
GitLab for Jira Appを展開します。
Jira Connectの追加オーディエンスURLに、追加のオーディエンスを入力します（例: https://gitlab.mycompany.com）。
変更を保存を選択します。