Merge branch 'docs-bprescott-20200730-jira' into 'master'

Docs: Jira DVCS improvements and make behavior of service templates clearer

Closes #232667

See merge request gitlab-org/gitlab!38346

doc/integration/jira_development_panel.md

@@ -92,9 +92,6 @@ If you're using GitLab.com and Jira Cloud, we recommend you use the [GitLab for
    If you're using Jira Cloud, go to **Settings (gear) > Products > DVCS accounts**.
 1. Click **Link GitHub Enterprise account** to start creating a new integration.
    (We're pretending to be GitHub in this integration, until there's additional platform support in Jira.)
-
-   ![Jira Settings](img/jira_dev_panel_jira_setup_1-1.png)
-
 1. Complete the form:
 
    Select **GitHub Enterprise** for the **Host** field.
@@ -134,6 +131,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.

doc/user/project/integrations/jira.md

@@ -22,7 +22,9 @@ Features include:
   - The Jira issue shows the activity and is closed or otherwise transitioned as specified in your GitLab settings.
 - **View a list of Jira issues directly in GitLab** **(PREMIUM)**
 
-For additional features, you can install the [Jira Development Panel integration](../../../integration/jira_development_panel.md). This enables you to:
+For additional features, you can install the
+[Jira Development Panel integration](../../../integration/jira_development_panel.md) **(PREMIUM)**.
+This enables you to:
 
 - In a Jira issue, display relevant GitLab information in the [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/), including related branches, commits, and merge requests.
 - Use Jira [Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html) in GitLab to add Jira comments, log time spent on the issue, or apply any issue transition.