GitLab for Jira クラウドアプリ

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

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

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

Jira Data Center または Jira Server を使用している場合は、アトラシアンが開発・メンテナーしているJira DVCS コネクターを使用してください。

Jira に同期された GitLab データ

グループをリンクした後、Jira イシュー ID に言及すると、そのグループ内のすべてのプロジェクトについて以下の GitLab データが Jira に同期されます：

  • 既存のプロジェクトデータ (グループをリンクする前のもの)：
    • 直近400件のマージリクエスト
    • 直近の 400 ブランチと、それぞれのブランチへの直近のコミット (GitLab 15.11 以降)
  • 新しいプロジェクトデータ（グループをリンクした後）：
    • マージリクエスト
    • ブランチ
    • コミット
    • ビルド
    • デプロイメント
    • フィーチャーフラグ

GitLab for Jira Cloud アプリのインストール

前提条件：

  • Jira インスタンスへのサイト管理者アクセス権を持っている必要があります。
  • ネットワークが GitLab と Jira 間のインバウンドおよびアウトバウンド接続を許可している必要があります。

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

  1. Jira のトップバーで、[アプリ] > [その他のアプリを検索] を選択し、GitLab for Jira Cloudを検索します。
  2. GitLab for Jira Cloud を選択し、Get it now を選択します。

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

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

概要については、Atlassian Marketplace からの GitLab for Jira Cloud アプリの設定を参照してください。

GitLab for Jira Cloud アプリの設定

GitLab 16.1のLinkグループにリネームされた名前空間を追加します。

前提条件：

  • 少なくとも GitLab グループのメンテナー ロールを持っている必要があります。
  • Jira インスタンスへのサイト管理者アクセス権を持っている必要があります。

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

  1. Jira のトップバーで、アプリ > アプリの管理 を選択します。
  2. GitLab for Jira を展開します。
  3. Get started を選択します。
  4. オプション。GitLab バージョンを変更] を選択して、Jira で使用する GitLab インスタンスを設定します。
    • GitLab.com (SaaS)またはGitLab (自己管理) を選択し、[保存] を選択します。
    • GitLab（セルフマネージド）の場合は、GitLabインスタンスのURLを入力する必要があります。
  5. Sign into GitLabを選択します。
  6. リンクできるグループの一覧は、Link groups を選択します。
  7. グループにリンクするには、[リンク] を選択します。

GitLab グループにリンクすると、そのグループ内のすべてのプロジェクトのデータが Jira に同期されます。最初のデータ同期は、1 分間に 20 プロジェクトのバッチで行われます。プロジェクト数が多いグループの場合、一部のプロジェクトのデータ同期が遅れます。

GitLab for Jira Cloud アプリのアップデート

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

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

自己管理インスタンス用の OAuth 認証のセットアップ

GitLab for Jira Cloud アプリはOAuth 認証に切り替わっています。OAuth 認証を有効にするには、GitLab インスタンス上に OAuth アプリケーションを作成する必要があります。

OAuth 認証を有効にするには、以下の手順が必要です：

OAuth アプリケーションを作成します：

  1. 左のサイドバーで、Search を選択するか、次のページに進んでください。
  2. Admin Areaを選択します。
  3. 左サイドバーで「アプリケーション」を選択します。
  4. 新規アプリケーションを選択します。
  5. リダイレクトURIで
    • 公式マーケットプレイスのリストからアプリをインストールする場合は、https://gitlab.com/-/jira_connect/oauth_callbacks を入力してください。
    • 手動でアプリをインストールする場合は、<instance_url>/-/jira_connect/oauth_callbacks と入力し、<instance_url> をインスタンスの URL に置き換えてください。
  6. Trustedと Confidentialのチェックボックスをオフにします。
  7. スコープ］で、［api ］チェックボックスのみを選択します。
  8. Save applicationを選択します。
  9. アプリケーションIDの値をコピーします。
  10. 左サイドバーで、設定 > 一般を選択します。
  11. GitLab for Jira App を展開します。
  12. アプリケーション ID の値をJira Connect アプリケーション ID に貼り付けます。
  13. 変更を保存を選択します。

セルフマネージドインスタンス用の GitLab for Jira Cloud アプリを接続します。

GitLab 15.7 で導入されました。

マーケットプレイスから GitLab for Jira Cloud アプリをインストールした後、セルフマネージドインスタンスをリンクできます。Jira アプリは、マーケットプレイスのリストごとに 1 つの URL にのみリンクできます。公式リストは GitLab.com にリンクします。

note
この方法では、GitLab.com がインスタンスからの Jira トラフィックのプロキシとして機能します。

インスタンスが前提条件を満たしていない場合や、公式マーケットプレイスのリストを使いたくない場合は、手動でアプリをインストールすることができます。

この方法では、自己管理インスタンス用の Jira Cloud からブランチを作成することはできません。詳細については、イシュー 391432 を参照してください。Jira Cloud からブランチを作成するには、アプリを手動でインストールしてください。

前提条件

  • インスタンスは公開されている必要があります。
  • インスタンスがGitLabバージョン15.7以降であること。
  • OAuth認証を設定する必要があります。
  • ネットワークが GitLab と Jira 間のインバウンドおよびアウトバウンド接続を許可している必要があります。ファイアウォールの背後にあり、インターネットから直接アクセスできない自己管理インスタンスの場合：
    • ファイアウォールを開き、アトラシアンの IP アドレスからのインバウンドトラフィックのみを許可してください。
    • 自己管理インスタンスの前にインターネットに面したリバースプロキシーを設定します。このプロキシをさらにセキュリティで保護するために、Atlassian IP アドレスからのインバウンドトラフィックのみを許可します。
    • GitLab IP アドレスをファイアウォールの allowlist に追加します。

インスタンスの設定

前提条件

GitLab 15.7 以降で GitLab for Jira Cloud アプリのセルフマネージドインスタンスをセットアップするには：

  1. 左のサイドバーで、Search を選択するか、次のページに進んでください。
  2. Admin Areaを選択します。
  3. 左サイドバーで、設定 > 一般を選択します。
  4. GitLab for Jira App を展開します。
  5. Jira Connect Proxy URL にhttps://gitlab.com と入力します。
  6. 変更を保存を選択します。

前提条件

セルフマネージドインスタンスを GitLab for Jira Cloud アプリにリンクします：

  1. GitLab for Jira Cloud アプリをインストールします。
  2. GitLab (自己管理) を選択します。
  3. GitLab インスタンスの URL を入力します。
  4. Save を選択します。

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

GitLab インスタンスが自己管理されていて、公式マーケットプレイスのリストを使いたくない場合は、アプリを手動でインストールすることができます。

各 Jira Cloud アプリケーションは 1 つの場所からインストールする必要があります。Jira は提供された場所からマニフェストファイルをフェッチします。マニフェスト ファイルはアプリケーションをシステムに説明します。Jira Cloud で自己管理型 GitLab インスタンスをサポートするには、次のいずれかを実行します：

前提条件

  • インスタンスは公開されている必要があります。
  • OAuth認証を設定する必要があります。

開発者モードでアプリケーションをインストールします。

前提条件

マーケットプレイス外からアプリケーションをインストールできるように Jira インスタンスを設定するには：

  1. 管理者として Jira インスタンスにサインインします。
  2. Jira インスタンスを開発モードにします。
  3. GitLab アプリケーションに管理者権限を持つユーザーとしてサインインします。
  4. アトラシアン開発者ガイドに記載されているように、Jira インスタンスから GitLab アプリケーションをインストールします：
    1. Jira インスタンスで、アプリ > アプリの管理に進み、アプリのアップロードを選択します：
    2. アプリ記述子 URL には、インスタンス設定に基づくマニフェスト ファイルへの完全な URL を指定します。デフォルトでは、マニフェストファイルは/-/jira_connect/app_descriptor.json にあります。例えば、GitLab セルフマネージドインスタンスのドメインがapp.pet-store.cloudの場合、マニフェストファイルはhttps://app.pet-store.cloud/-/jira_connect/app_descriptor.jsonにあります。
    3. アップロード] を選択します。Jira はapp_descriptor ファイルのコンテンツをフェッチし、インストールします。
    4. インテグレーションを設定するには、[開始] を選択します。
  5. Jira インスタンスで開発モードを無効にします。

GitLab for Jira Cloudアプリがアプリの管理の下に表示されるようになりました。Get startedを選択して GitLab インスタンスからレンダリングされた設定ページを開くこともできます。

note
GitLab のアップデートによってアプリケーション記述子が変更された場合は、アプリケーションをアンインストールしてから再インストールする必要があります。

マーケットプレイスのリストを作成

前提条件

Jira インスタンスで開発モードを使用したくない場合、独自のマーケットプレイスリストを作成することができます。この方法で、あなたのアプリケーションを Atlassian Marketplace からインストールできます。

マーケットプレイスのリストを作成するには

  1. マーケットプレイスのベンダーとして登録します。
  2. アプリケーション記述子 URL を使用してアプリケーションをリストします。
    • マニフェストファイルは次の場所にあります：https://your.domain/your-path/-/jira_connect/app_descriptor.json
    • 公開アプリケーションはどのユーザーでも閲覧およびインストールできるため、アプリケーションをprivate としてリストする必要があります。
  3. アプリケーションのテストライセンストークンを生成します。
note
この方法は、GitLab.com Marketplace のリストと同じように自動更新を使用します。

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

GitLab for Jira Cloud アプリのプロキシとして機能するように GitLab インスタンスを設定します。

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

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

  1. 左のサイドバーで、Search を選択するか、次のページに進んでください。
  2. Admin Areaを選択します。
  3. 左サイドバーで、設定 > 一般を選択します。
  4. GitLab for Jira App を展開します。
  5. 公開鍵ストレージを有効にする] を選択します。
  6. 変更を保存を選択します。
  7. GitLab for Jira Cloud アプリを手動でインストールします。

プロキシを使用する他の GitLab インスタンスは、Jira Connect プロキシ URLとOAuth アプリケーションの リダイレクト URI設定をプロキシインスタンスを指すように設定する必要があります。

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

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

OAuth による GitLab へのアクセス

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

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

OAuth アプリケーションはapi スコープを持たなければなりません。これは API への完全な読み書きアクセスを許可するものです。このアクセスには、すべてのグループとプロジェクト、コンテナレジストリ、パッケージレジストリが含まれます。しかし、GitLab for Jira Cloud アプリは、このアクセスのみを使用します：

  • リンクするグループを表示します。
  • グループをリンクします。

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

アクセストークンによる Jira へのアクセス

Jira は GitLab とアクセストークンを共有し、Jira へのデータプッシュの認証と作成者を承認します。アプリインストールプロセスの一部として、Jira はアクセストークンを含むハンドシェイクリクエストを GitLab に送信します。ハンドシェークは非対称 JWT で署名され、アクセストークンは GitLab 上のAES256-GCM で暗号化されて保存されます。

トラブルシューティング

すでにサインインしているのに、ブラウザにサインインのメッセージが表示されます。

すでに GitLab.com にサインインしているときに、サインインを促す次のようなメッセージが表示されることがあります：

You need to sign in or sign up before continuing.

GitLab for Jira Cloud アプリは、設定ページでグループを追加するために iframe を使用しています。ブラウザによってはクロスサイトクッキーをブロックしているため、このイシューが発生する可能性があります。

このイシューを解決するには、OAuth 認証を設定してください。

手動インストールに失敗します。

公式マーケットプレイスのリストから GitLab for Jira Cloud アプリをインストールし、手動インストールに置き換えた場合、エラーが表示されることがあります：

The app "gitlab-jira-connect-gitlab.com" could not be installed as a local app as it has previously been installed from Atlassian Marketplace

このイシューを解決するには、Jira Connect Proxy URL設定を無効にしてください。

  • GitLab 15.7：

    1. Railsコンソールを開きます。
    2. 実行ApplicationSetting.current_without_cache.update(jira_connect_proxy_url: nil) 。

  • GitLab 15.8以降では：

    1. 左のサイドバーで、Search を選択するか、次のページに進んでください。
    2. Admin Areaを選択します。
    3. 左サイドバーで、設定 > 一般を選択します。
    4. GitLab for Jira App を展開します。
    5. Jira Connect Proxy URLテキストボックスをクリアします。
    6. 変更を保存を選択します。

Invalid JWT エラーで同期に失敗します。

GitLab for Jira Cloud アプリが継続的にデータの同期に失敗する場合、シークレットトークンが古いことが原因である可能性があります。アトラシアンは新しいシークレットトークンを送信することができ、GitLab がそれを処理して保存する必要があります。GitLab がトークンの保存に失敗したり、新しいトークンのリクエストを見逃したりすると、Invalid JWT エラーが発生します。

GitLab 自己管理でこのイシューを解決するには、アプリのインストール方法に応じて、以下のいずれかの解決策に従ってください。

  • 公式マーケットプレイスのリストからアプリをインストールした場合：

    1. Jira で GitLab for Jira Cloud アプリを開きます。
    2. Change GitLab version を選択します。
    3. GitLab.com（SaaS）を選択します。
    4. Change GitLab versionagainを選択します。
    5. GitLab (自己管理) を選択します。
    6. GitLab インスタンスの URL を入力します。
    7. Save を選択します。

  • GitLab for Jira Cloud アプリを手動でインストールした場合：

    • GitLab 14.9 以降の場合：
      • Jira Software Cloud サポートに連絡し、グループ内の GitLab for Jira Cloud アプリの新しいインストール済みライフサイクルイベントをトリガーするよう依頼してください。
    • すべての GitLab バージョンで：
      • GitLab for Jira Cloud アプリを再インストールしてください。この方法では、Jira 開発パネルから同期データがすべて削除される可能性があります。

Failed to update the GitLab instance セルフマネージドインスタンスの場合

GitLab for Jira Cloud アプリをセットアップする際、セルフマネージドインスタンスの URL を入力するとFailed to update the GitLab instance エラーが表示されることがあります。

このイシューを解決するには、インストール方法の前提条件がすべて満たされていることを確認してください：

GitLab 15.8 以前を使用していて、jira_connect_oauth_self_managed とjira_connect_oauth 機能フラグの両方を有効にしている場合、既知のイシューのためjira_connect_oauth_self_managed フラグを無効にする必要があります。これらのフラグを確認するには：

  1. Railsコンソールを開きます。

  2. 以下のコードを実行します：

    # Check if both feature flags are enabled.
# If the flags are enabled, these commands return `true`.
Feature.enabled?(:jira_connect_oauth)
Feature.enabled?(:jira_connect_oauth_self_managed)
   
# If both flags are enabled, disable the `jira_connect_oauth_self_managed` flag.
Feature.disable(:jira_connect_oauth_self_managed)

GitLab for Jira Cloud アプリをセルフマネージドインスタンスに接続すると、以下のエラーが表示されることがあります：

Failed to load Jira Connect Application ID. Please try again.

Failed to link group. Please try again.

ブラウザのコンソールを確認すると、次のようなメッセージが表示されることがあります：

Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at https://gitlab.example.com/-/jira_connect/oauth_application_id. (Reason: CORS header 'Access-Control-Allow-Origin' missing). Status code: 403.

以下の場合、403 ステータスコードが返されます：

  • ユーザー情報を Jira から取得できません。
  • 認証された Jira ユーザーはサイト管理者アクセス権を持っていません。

このイシューを解決するには、認証されたユーザーが Jira サイト管理者であることを確認し、再試行してください。