Add latest changes from gitlab-org/gitlab@13-3-stable-ee

1 files changed, 87 insertions, 0 deletions

diff --git a/doc/integration/jira_development_panel.md b/doc/integration/jira_development_panel.md
index dc19d42ee2e..7c646b95ae7 100644
--- a/doc/integration/jira_development_panel.md
+++ b/doc/integration/jira_development_panel.md
@@ -134,6 +134,93 @@ steps with additional Jira DVCS accounts.
 
 Now that the integration is configured, read more about how to test and use it in [Usage](#usage).
 
+#### Troubleshooting your DVCS connection
+
+Refer to the items in this section if you're having problems with your DVCS connector.
+
+##### Jira cannot access GitLab server
+
+```plaintext
+Error obtaining access token. Cannot access https://gitlab.example.com from Jira.
+```
+
+This error message is generated in Jira, after completing the **Add New Account**
+form and authorizing access. It indicates a connectivity issue from Jira to
+GitLab. No other error messages appear in any logs.
+
+If there was an issue with SSL/TLS, this error message will be generated.
+
+- The [GitLab Jira integration](jira.md) requires GitLab to connect to Jira. Any
+  TLS issues that arise from a private certificate authority or self-signed
+  certificate [are resolved on the GitLab server](https://docs.gitlab.com/omnibus/settings/ssl.html#other-certificate-authorities),
+  as GitLab is the TLS client.
+- The Jira Development Panel integration requires Jira to connect to GitLab, which
+  causes Jira to be the TLS client. If your GitLab server's certificate is not
+  issued by a public certificate authority, the Java truststore on Jira's server
+  needs to have the appropriate certificate added to it (such as your organization's
+  root certificate).
+
+Refer to Atlassian's documentation and Atlassian Support for assistance setting up Jira correctly:
+
+- [Adding a certificate to the trust store](https://confluence.atlassian.com/kb/how-to-import-a-public-ssl-certificate-into-a-jvm-867025849.html).
+  - Simplest approach is to use [keytool](https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html).
+  - Add additional roots to Java's default truststore (`cacerts`) to allow Jira to
+    also trust public certificate authorities.
+  - If the integration stops working after upgrading Jira's Java runtime, this
+    might be because the `cacerts` truststore got replaced.
+
+- [Troubleshooting connectivity up to and including TLS handshaking](https://confluence.atlassian.com/kb/unable-to-connect-to-ssl-services-due-to-pkix-path-building-failed-error-779355358.html),
+  using the a java class called `SSLPoke`.
+
+- Download the class from Atlassian's knowledgebase to Jira's server, for example to `/tmp`.
+- Use the same Java runtime as Jira.
+- Pass all networking-related parameters that Jira is called with, such as proxy
+  settings or an alternative root truststore (`-Djavax.net.ssl.trustStore`):
+
+```shell
+${JAVA_HOME}/bin/java -Djavax.net.ssl.trustStore=/var/atlassian/application-data/jira/cacerts -classpath /tmp SSLPoke gitlab.example.com 443
+```
+
+The message `Successfully connected` indicates a successful TLS handshake.
+
+If there are problems, the Java TLS library generates errors that you can
+look up for more detail.
+
+##### Jira error adding account and no repositories listed
+
+```plaintext
+Error!
+Failed adding the account: [Error retrieving list of repositories]
+```
+
+This error message is generated in Jira after completing the **Add New Account**
+form in Jira and authorizing access. Attempting to click **Try Again** returns
+`Account is already integrated with JIRA.` The account is set up in the DVCS
+accounts view, but no repositories are listed.
+
+Potential resolutions:
+
+- If you're using GitLab versions 11.10-12.7, upgrade to GitLab 12.8.10 or later
+  to resolve an identified [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/37012).
+- The Jira Development Panel integration requires GitLab Premium, GitLab.com Silver,
+  or a higher tier. If you're using a lower tier of GitLab, you'll need to upgrade
+  to use this feature.
+
+[Contact GitLab Support](https://about.gitlab.com/support) if none of these reasons apply.
+
+#### Fixing synchonization issues
+
+If Jira displays incorrect information (such as deleted branches), you may need to
+resynchronize the information. To do so:
+
+1. In Jira, go to **Jira Administration > Applications > DVCS accounts**.
+1. At the account (group or subgroup) level, Jira displays an option to
+   **Refresh repositories** in the `...` (ellipsis) menu.
+1. For each project, there's a sync button displayed next to the **last activity** date.
+   To perform a *soft resync*, click the button, or complete a *full sync* by shift clicking
+   the button. For more information, see
+   [Atlassian's documentation](https://confluence.atlassian.com/adminjiracloud/synchronize-an-account-972332890.html).
+
 ### GitLab for Jira app
 
 You can integrate GitLab.com and Jira Cloud using the [GitLab for Jira](https://marketplace.atlassian.com/apps/1221011/gitlab-for-jira) app in the Atlassian Marketplace.