From dd38f8a2f6522e024f459ef54a38213b14c710e2 Mon Sep 17 00:00:00 2001
From: Anton Smith <asmith@gitlab.com>
Date: Wed, 14 Feb 2024 08:42:30 +0000
Subject: [PATCH] Expand troubleshooting on invalid JWT errors
---
.../jira_cloud_app_troubleshooting.md | 67 +++++++++++++++----
1 file changed, 53 insertions(+), 14 deletions(-)
diff --git a/doc/administration/settings/jira_cloud_app_troubleshooting.md b/doc/administration/settings/jira_cloud_app_troubleshooting.md
index a765b12d11e04..ac4c00d2d3f05 100644
--- a/doc/administration/settings/jira_cloud_app_troubleshooting.md
+++ b/doc/administration/settings/jira_cloud_app_troubleshooting.md
@@ -67,27 +67,66 @@ curl --head "https://connect-install-keys.atlassian.com"
## Data sync fails with `Invalid JWT`
-If the GitLab for Jira Cloud app continuously fails to sync data, it may be due to an outdated secret token. Atlassian can send new secret tokens that must be processed and stored by GitLab.
-If GitLab fails to store the token or misses the new token request, an `Invalid JWT` error occurs.
+If the GitLab for Jira Cloud app continuously fails to sync data from a self-managed GitLab instance,
+a secret token might be outdated. Atlassian can send new secret tokens to GitLab.
+If GitLab fails to process or store these tokens, an `Invalid JWT` error occurs.
-To resolve this issue on GitLab self-managed, follow one of the solutions below, depending on your app installation method.
+To resolve this issue on your self-managed GitLab instance:
-- If you installed the app from the official marketplace listing:
+- Confirm your self-managed GitLab instance is publicly available to:
+ - GitLab.com (if you [installed the app from the official Atlassian Marketplace listing](jira_cloud_app.md#connect-the-gitlab-for-jira-cloud-app)).
+ - Jira Cloud (if you [installed the app manually](jira_cloud_app.md#install-the-gitlab-for-jira-cloud-app-manually)).
+- Ensure the token request sent to the `/-/jira_connect/events/installed` endpoint when you install the app is accessible from Jira.
+ The following `curl` command must return a `401` status code:
- 1. Open the GitLab for Jira Cloud app on Jira.
+ ```shell
+ curl --include --request POST "https://gitlab.example.com/-/jira_connect/events/installed"
+ ```
+
+- If your self-managed GitLab instance has [SSL configured](https://docs.gitlab.com/omnibus/settings/ssl/), check your
+ [certificates are valid and publicly trusted](https://docs.gitlab.com/omnibus/settings/ssl/ssl_troubleshooting.html#useful-openssl-debugging-commands).
+
+Depending on how you installed the app, you might want to check the following:
+
+- If you [installed the app from the official Atlassian Marketplace listing](jira_cloud_app.md#connect-the-gitlab-for-jira-cloud-app),
+ switch between GitLab versions in the GitLab for Jira Cloud app:
+
+ 1. In Jira, on the top bar, select **Apps > Manage your apps**.
+ 1. Expand **GitLab for Jira (GitLab.com)**.
+ 1. Select **Get started**.
1. Select **Change GitLab version**.
- 1. Select **GitLab.com (SaaS)**.
+ 1. Select **GitLab.com (SaaS)**, then select **Save**.
1. Select **Change GitLab version** again.
- 1. Select **GitLab (self-managed)**.
- 1. Enter your **GitLab instance URL**.
- 1. Select **Save**.
+ 1. Select **GitLab (self-managed)**, then select **Next**.
+ 1. Select all checkboxes, then select **Next**.
+ 1. Enter your **GitLab instance URL**, then select **Save**.
+
+ If this method does not work, [submit a support ticket](https://support.gitlab.com/hc/en-us/requests/new) if you're a Premium or Ultimate customer
+ and provide your GitLab instance URL and Jira URL. GitLab Support can try to run the following scripts to resolve the issue:
+
+ ```ruby
+ # Check if GitLab.com can connect to the 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
+ ```
+
+ ```ruby
+ # Locate the installation record for the self-managed instance
+ installation = JiraConnectInstallation.find_by_instance_url("https://gitlab.example.com")
-- If you [installed the GitLab for Jira Cloud app manually](jira_cloud_app.md#install-the-gitlab-for-jira-cloud-app-manually):
+ # Try to send the token again from GitLab.com to the self-managed instance
+ ProxyLifecycleEventService.execute(installation, :installed, installation.instance_url)
+ ```
- - In GitLab 14.9 and later:
- - Contact the [Jira Software Cloud support](https://support.atlassian.com/jira-software-cloud/) and ask to trigger a new installed lifecycle event for the GitLab for Jira Cloud app in your group.
- - In all GitLab versions:
- - Re-install the GitLab for Jira Cloud app. This method might remove all synced data from the [Jira development panel](../../integration/jira/development_panel.md).
+- If you [installed the app manually](jira_cloud_app.md#install-the-gitlab-for-jira-cloud-app-manually):
+ - Ask [Jira Cloud Support](https://support.atlassian.com/jira-software-cloud/) to verify that Jira can connect to your
+ self-managed GitLab instance.
+ - [Reinstall the app](jira_cloud_app.md#install-the-gitlab-for-jira-cloud-app-manually). This method might remove all [synced data](../../integration/jira/connect-app.md#gitlab-data-synced-to-jira) from the [Jira development panel](../../integration/jira/development_panel.md).
## `Failed to update the GitLab instance`
--
GitLab