Jira Cloudアプリの管理におけるGitLabのトラブルシューティング

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

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

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

すでにサインインしている場合に、GitLab.comへのサインインを求める次のメッセージが表示されることがあります:

Sign in or sign up before continuing.

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

このイシューを解決するには、OAuth認証を設定します。

手動インストールが失敗する

公式のMarketplaceリストから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

The app host returned HTTP response code 401 when we tried to contact it during installation. Please try again later or contact the app vendor.

このイシューを解決するには、Jira ConnectのプロキシURL設定を無効にします。

GitLab 15.7の場合:
1. Railsコンソールを開きます。
2. ApplicationSetting.current_without_cache.update(jira_connect_proxy_url: nil)を実行します。
GitLab 15.8以降では、次のようになります:
1. 左側のサイドバーの下部で、管理者を選択します。
2. 左側のサイドバーで、設定 > 一般を選択します。
3. GitLab for Jira Appを展開します。
4. Jira ConnectのプロキシURLテキストボックスをクリアします。
5. 変更を保存を選択します。

イシューが解決しない場合は、インスタンスがconnect-install-keys.atlassian.comに接続してAtlassianから公開キーを取得できることを確認します。接続をテストするには、次のコマンドを実行します:

# A `404 Not Found` is expected because you're not passing a token
curl --head "https://connect-install-keys.atlassian.com"

`Invalid JWT`でデータ同期が失敗する

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

この問題を解決するには、以下を実行します:

インスタンスが以下に対して公開されていることを確認します:
- 公式のAtlassian Marketplaceリストからアプリをインストールした場合のGitLab.com。
- アプリを手動でインストールした場合のJira Cloud。
アプリのインストール時に/-/jira_connect/events/installedエンドポイントに送信されたトークンリクエストがJiraからアクセスできることを確認します。次のコマンドは、401 Unauthorizedを返す必要があります:
```
curl --include --request POST "https://gitlab.example.com/-/jira_connect/events/installed"
```
インスタンスにSSLが設定されている場合は、証明書が有効で、公開的に信頼されていることを確認してください。

アプリのインストール方法に応じて、次のことを確認してください:

公式のAtlassian Marketplaceリストからアプリをインストールした場合は、GitLab for Jira CloudアプリでGitLabバージョンを切り替えます:
1. Jiraで、Apps（アプリ）の横にある横の省略記号（）を選択し、Manage your apps（アプリの管理）を選択します。
2. 次のいずれかの方法を使用してアプリに移動します:
  For instances with centralized app management:（一元化されたアプリ管理を備えたインスタンスの場合:）
  1. 「App management has moved to Administration」（アプリの管理が管理に移動しました）と表示された場合は、Take me there（そちらに移動）を選択します。それ以外の場合は、For instances with legacy app management（従来のアプリ管理を使用するインスタンス）の手順に従ってください。
  2. Installed apps（インストール済みアプリ）タブで、**GitLab for Jira (gitlab.com)**アプリを見つけ、横の省略記号（）を選択し、始めましょうを選択します。
  For instances with legacy app management:（従来のアプリ管理を使用するインスタンスの場合:）
  1. **GitLab for Jira (gitlab.com)**アプリを見つけ、シェブロン（）を選択し、始めましょうを選択します。
3. GitLabのバージョンを変更を選択します。
4. **GitLab.com (SaaS)**を選択し、保存を選択します。
5. もう一度GitLabのバージョンを変更を選択します。
6. **GitLab(Self-Managed)**を選択し、次へを選択します。
7. すべてのチェックボックスをオンにし、次へを選択します。
8. GitLabインスタンスのURLを入力し、保存を選択します。
この方法でうまくいかない場合は、PremiumまたはUltimateプランのお客様の場合は、サポートチケットを送信してください。GitLabインスタンスのURLとJiraのURLを入力してください。GitLabサポートは、次のスクリプトを実行してイシューを解決できます:
```
# Check if GitLab.com can connect to the GitLab Self-Managed instance
checker = Gitlab::TcpChecker.new("gitlab.example.com", 443)

# Returns `true` if successful
checker.check

# Returns an error if the check fails
checker.error
```
```
# Locate the installation record for the GitLab Self-Managed instance
installation = JiraConnectInstallation.find_by_instance_url("https://gitlab.example.com")

# Try to send the token again from GitLab.com to the GitLab Self-Managed instance
ProxyLifecycleEventService.execute(installation, :installed, installation.instance_url)
```
アプリを手動でインストールした場合:
- Jira Cloud Supportに、Jiraがインスタンスに接続できることを確認するように依頼してください。
- アプリを再インストールします。この方法では、Jira開発パネルからすべての同期データが削除される可能性があります。

エラー: `Failed to update the GitLab instance`

GitLab for Jira Cloudアプリをセットアップするときに、GitLab Self-ManagedインスタンスのURLを入力すると、Failed to update the GitLab instanceエラーが発生する場合があります。

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

Jira Connectのプロキシ URLを設定し、前提条件を確認しても問題が解決しない場合は、Jira Connectのプロキシの問題のデバッグを確認してください。

GitLab 15.8以前のバージョンを使用していて、jira_connect_oauth_self_managedおよびjira_connect_oauthの両方の機能フラグを以前に有効にしている場合は、既知のイシューが原因で、jira_connect_oauth_self_managedフラグを無効にする必要があります。これらのフラグを確認するには:

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

次のコードを実行します:

# 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)

エラー: `Invalid audience`

リバースプロキシを使用している場合、exceptions_json.logに次のようなメッセージが含まれている可能性があります:

Invalid audience. Expected https://proxy.example.com/-/jira_connect, received https://gitlab.example.com/-/jira_connect

このイシューを解決するには、リバースプロキシFQDNを追加のJWTオーディエンスとして設定します。

Jira Connectのプロキシのイシューのデバッグ

Jira ConnectのプロキシURLをhttps://gitlab.comに設定してインスタンスをセットアップすると、次のことができます:

ブラウザの開発パネルでネットワークトラフィックを調べます。
詳細については、Failed to update the GitLab instanceエラーを再現してください。

GETからhttps://gitlab.com/-/jira_connect/installationsへのリクエストが表示されるはずです。

このリクエストは200 OKを返すはずですが、問題が発生した場合は422 Unprocessable Entityを返す可能性があります。応答本文でエラーを確認できます。

イシューを解決できず、GitLabのお客様である場合は、GitLabサポートにご連絡ください。次の情報をGitLabサポートに提供してください:

GitLab Self-ManagedインスタンスのURL。
GitLab.comのユーザー名。
オプション。https://gitlab.com/-/jira_connect/installationsへの失敗したGETリクエストのX-Request-Id応答ヘッダー。
オプション。イシューをキャプチャしたharcleanerで処理したHARファイル。

GitLabサポートは、GitLab.comサーバーログでイシューを調査できます。

GitLabサポート

これらの手順は、GitLabサポートのみが実行できます。

Jira ConnectプロキシURL https://gitlab.com/-/jira_connect/installationsへの各GETリクエストは、2つのログエントリを生成します。

Kibanaで関連するログエントリを見つけるには、次のいずれかを行います:

https://gitlab.com/-/jira_connect/installationsへのGETリクエストのX-Request-Id値または相関IDがある場合、Kibanaログは、json.meta.caller_id: JiraConnect::InstallationsController#update、NOT json.status: 200、およびjson.correlation_id: <X-Request-Id>でフィルタリングする必要があります。これにより、2つのログエントリが返されます。
お客様のSelf-Managed URLがある場合:
1. Kibanaログは、json.meta.caller_id: JiraConnect::InstallationsController#update、NOT json.status: 200、およびjson.params.value: {"instance_url"=>"https://gitlab.example.com"}でフィルタリングする必要があります。Self-Managed URLに先頭のスラッシュを含めることはできません。これにより、ログエントリの1つが返されます。
2. json.correlation_idをフィルターに追加します。
3. json.params.valueフィルターを削除します。これにより、もう一方のログエントリが返されます。

最初のログの場合:

json.statusが422 Unprocessable Entityと等しい。
json.params.valueは、GitLab Self-Managed URL [[FILTERED], {"instance_url"=>"https://gitlab.example.com"}]と一致する必要があります。

2番目のログでは、次のいずれかのシナリオが発生する可能性があります:

シナリオ1:
- json.message、json.jira_status_code、およびjson.jira_bodyが存在します。
- json.messageはProxy lifecycle event received error responseまたは類似しています。
- json.jira_status_codeおよびjson.jira_bodyには、GitLab Self-Managedインスタンスまたはインスタンスの前面にあるプロキシから受信した応答が含まれている可能性があります。
- json.jira_status_codeが401 Unauthorizedで、json.jira_bodyが(empty)の場合:
  - Jira ConnectのプロキシURLがhttps://gitlab.comに設定されていない可能性があります。
  - GitLab Self-Managedインスタンスが送信接続をブロックしている可能性があります。GitLab Self-Managedインスタンスがconnect-install-keys.atlassian.comとgitlab.comの両方に接続できることを確認してください。
  - GitLab Self-Managedインスタンスは、JiraからのJWTトークンを復号化できません。GitLab 16.11以降、exceptions_json.logにはエラーに関する詳細情報が含まれています。
  - リバースプロキシがGitLab Self-Managedインスタンスの前面にある場合、GitLab Self-Managedインスタンスに送信されるHostヘッダーがリバースプロキシFQDNと一致しない可能性があります。GitLab Self-ManagedインスタンスのWorkhorseログを確認します:
    grep /-/jira_connect/events/installed /var/log/gitlab/gitlab-workhorse/current
    出力には、次のものが含まれている可能性があります:
    { "host":"gitlab.mycompany.com:443", // The host should match the reverse proxy FQDN entered into the GitLab for Jira Cloud app "remote_ip":"34.74.226.3", // This IP should be within the GitLab.com IP range https://docs.gitlab.com/ee/user/gitlab_com/#ip-range "status":401, "uri":"/-/jira_connect/events/installed" }
- json.jira_status_codeが404 Not Foundで、json.jira_bodyに一般的なGitLab 404ページHTMLが含まれている場合は、Self-Managedインスタンスのインテグレーション許可リストがGitLab for Jira Cloudアプリを許可していることを確認します。
シナリオ2:
- json.exception.classとjson.exception.messageが存在します。
- json.exception.classおよびjson.exception.messageには、GitLab Self-Managedインスタンスへの接続中に問題が発生したかどうかが含まれています。

エラー: `Failed to link group`

グループをリンクすると、次のエラーが発生する可能性があります:

Failed to link group. Please try again.

このエラーは、複数の理由で返される可能性があります。

権限が不十分でJiraからユーザー情報を取得できない場合、403 Forbiddenが返されます。このイシューを解決するには、アプリをインストールして構成するJiraユーザー名が特定の要件を満たしていることを確認してください。
このエラーは、リバースプロキシで書き換えまたはサブフィルターを使用する場合にも発生する可能性があります。リクエストで使用されるアプリキーには、一部のリバースプロキシフィルターがキャプチャする可能性のあるサーバーホスト名の一部が含まれています。認証が正しく機能するためには、AtlassianとGitLabのアプリキーが一致する必要があります。
このエラーは、GitLab for Jira Cloudアプリが最初にインストールされたときにGitLabインスタンスが最初に誤って構成された場合に発生する可能性があります。この場合、jira_connect_installationテーブル内のデータを削除する必要があるかもしれません。既存のGitLab for Jiraアプリのインストールを保持する必要がないことを確認した場合にのみ、このデータを削除してください。
1. JiraプロジェクトからGitLab for Jira Cloudアプリをアンインストールします。
2. レコードを削除するには、GitLab Railsコンソールで次のコマンドを実行します:
```
JiraConnectInstallation.delete_all
```

エラー: `Failed to load Jira Connect Application ID`

アプリをGitLab Self-Managedインスタンスに向けた後、GitLab for Jira Cloudアプリにサインインすると、次のエラーが発生する場合があります:

Failed to load Jira Connect Application ID. 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.

この問題を解決するには、以下を実行します:

/-/jira_connect/oauth_application_idが公開されており、JSON応答を返すことを確認します:
```
curl --include "https://gitlab.example.com/-/jira_connect/oauth_application_id"
```
公式のAtlassian Marketplaceリストからアプリをインストールした場合は、Jira ConnectのプロキシURLが末尾にスラッシュなしでhttps://gitlab.comに設定されていることを確認してください。

エラー: `Missing required parameter: client_id`

アプリをGitLab Self-Managedインスタンスに向けた後、GitLab for Jira Cloudアプリにサインインすると、次のエラーが発生する場合があります:

Missing required parameter: client_id

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

エラー: `Failed to sign in to GitLab`

アプリをGitLab Self-Managedインスタンスに向けた後、GitLab for Jira Cloudアプリにサインインすると、次のエラーが発生する場合があります:

Failed to sign in to GitLab

このイシューを解決するには、アプリ用に作成されたOAuthアプリケーションで、信用済みと非公開のチェックボックスがオフになっていることを確認します。

Jira Cloudアプリの管理におけるGitLabのトラブルシューティング

すでにサインインしている場合にサインインメッセージが表示される

手動インストールが失敗する

Invalid JWTでデータ同期が失敗する

エラー: Failed to update the GitLab instance

エラー: Invalid audience

Jira Connectのプロキシのイシューのデバッグ

GitLabサポート

エラー: Failed to link group

エラー: Failed to load Jira Connect Application ID

エラー: Missing required parameter: client_id

エラー: Failed to sign in to GitLab

`Invalid JWT`でデータ同期が失敗する

エラー: `Failed to update the GitLab instance`

エラー: `Invalid audience`

エラー: `Failed to link group`

エラー: `Failed to load Jira Connect Application ID`

エラー: `Missing required parameter: client_id`

エラー: `Failed to sign in to GitLab`