diff options
Diffstat (limited to 'doc/integration/jira/connect-app.md')
| -rw-r--r-- | doc/integration/jira/connect-app.md | 93 |
1 files changed, 50 insertions, 43 deletions
diff --git a/doc/integration/jira/connect-app.md b/doc/integration/jira/connect-app.md index d274710b3cd..27f482ee2ba 100644 --- a/doc/integration/jira/connect-app.md +++ b/doc/integration/jira/connect-app.md @@ -6,34 +6,39 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab.com for Jira Cloud app **(FREE)** +You can integrate GitLab and Jira Cloud using the +[GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud) +app in the Atlassian Marketplace. + NOTE: -Only Jira users with administrator level access are able to install or configure +Only Jira users with the administrator role can install or configure the GitLab.com for Jira Cloud app. -## GitLab.com for Jira Cloud app **(FREE SAAS)** +## Install the GitLab.com for Jira Cloud app **(FREE SAAS)** -You can integrate GitLab.com and Jira Cloud using the -[GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud) -app in the Atlassian Marketplace. The user configuring GitLab.com for Jira Cloud app must have -[Maintainer](../../user/permissions.md) permissions in the GitLab.com namespace. +If you use GitLab.com and Jira Cloud, you can install the GitLab.com for Jira Cloud app. +If you do not use both of these environments, use the [Jira DVCS Connector](dvcs.md) or +[install GitLab.com for Jira Cloud app for self-managed instances](#install-the-gitlabcom-for-jira-cloud-app-for-self-managed-instances). +We recommend the GitLab.com for Jira Cloud app, because data is +synchronized in real time. The DVCS connector updates data only once per hour. -This integration method supports [smart commits](dvcs.md#smart-commits). +The user configuring the GitLab.com for Jira Cloud app must have +at least the [Maintainer](../../user/permissions.md) role in the GitLab.com namespace. -This method is recommended when using GitLab.com and Jira Cloud because data is -synchronized in real-time. The DVCS connector updates data only once per hour. -If you are not using both of these environments, use the [Jira DVCS Connector](dvcs.md) method or -[steps to install GitLab.com for Jira Cloud app for self-managed instances](#install-the-gitlabcom-for-jira-cloud-app-for-self-managed-instances). +This integration method supports [Smart Commits](dvcs.md#smart-commits). <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For a walkthrough of the integration with GitLab.com for Jira Cloud app, watch [Configure GitLab.com Jira Could Integration using Marketplace App](https://youtu.be/SwR-g1s1zTo) on YouTube. -1. Go to **Jira Settings > Apps > Find new apps**, then search for GitLab. -1. Click **GitLab.com for Jira Cloud**, then click **Get it now**, or go to the +To install the GitLab.com for Jira Cloud app: + +1. In Jira, go to **Jira Settings > Apps > Find new apps**, then search for GitLab. +1. Select **GitLab.com for Jira Cloud**, then select **Get it now**, or go to the [App in the marketplace directly](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud).  -1. After installing, click **Get started** to go to the configurations page. +1. After installing, to go to the configurations page, select **Get started**. This page is always available under **Jira Settings > Apps > Manage apps**.  @@ -41,7 +46,7 @@ For a walkthrough of the integration with GitLab.com for Jira Cloud app, watch [Maintainer](../../user/permissions.md) permissions to add namespaces.  -1. Select **Add namespace** to open the list of available namespaces. +1. To open the list of available namespaces, select **Add namespace**. 1. Identify the namespace you want to link, and select **Link**. Only Jira site administrators are permitted to add or remove namespaces for an installation. @@ -89,30 +94,30 @@ from outside the Marketplace, which allows you to install the application: 1. Sign in to your Jira instance as a user with an Administrator role. 1. Place your Jira instance into [development mode](https://developer.atlassian.com/cloud/jira/platform/getting-started-with-connect/#step-2--enable-development-mode). -1. Sign in to your GitLab application as a user with an [Administrator](../../user/permissions.md) role. +1. Sign in to your GitLab application as an [administrator](../../user/permissions.md). 1. Install the GitLab application from your self-managed GitLab instance, as described in the [Atlassian developer guides](https://developer.atlassian.com/cloud/jira/platform/getting-started-with-connect/#step-3--install-and-test-your-app): - 1. In your Jira instance, go to **Apps > Manage Apps** and click **Upload app**: + 1. In your Jira instance, go to **Apps > Manage Apps** and select **Upload app**: -  +  - 1. For **App descriptor URL**, provide full URL to your manifest file, modifying this - URL based on your instance configuration: `https://your.domain/your-path/-/jira_connect/app_descriptor.json` - 1. Click **Upload**, and Jira fetches the content of your `app_descriptor` file and installs - it for you. + 1. For **App descriptor URL**, provide the full URL to your manifest file, based + on your instance configuration. For example: `https://your.domain/your-path/-/jira_connect/app_descriptor.json`. + 1. Select **Upload**. Jira fetches the content of your `app_descriptor` file and installs + it. 1. If the upload is successful, Jira displays a modal panel: **Installed and ready to go!** - Click **Get started** to configure the integration. + To configure the integration, select **Get started**. -  +  1. Disable [development mode](https://developer.atlassian.com/cloud/jira/platform/getting-started-with-connect/#step-2--enable-development-mode) on your Jira instance. The **GitLab.com for Jira Cloud** app now displays under **Manage apps**. You can also -click **Get started** to open the configuration page rendered from your GitLab instance. +select **Get started** to open the configuration page rendered from your GitLab instance. NOTE: -If a GitLab update makes changes to the application descriptor, you must uninstall, then reinstall, the -application. +If a GitLab update makes changes to the application descriptor, you must uninstall, +then reinstall the application. ### Create a Marketplace listing @@ -120,31 +125,33 @@ If you prefer to not use development mode on your Jira instance, you can create your own Marketplace listing for your instance. This enables your application to be installed from the Atlassian Marketplace. -For full instructions, review the Atlassian [guide to creating a marketplace listing](https://developer.atlassian.com/platform/marketplace/installing-cloud-apps/#creating-the-marketplace-listing). To create a -Marketplace listing, you must: +For full instructions, review the Atlassian [guide to creating a marketplace listing](https://developer.atlassian.com/platform/marketplace/installing-cloud-apps/#creating-the-marketplace-listing). +To create a Marketplace listing: 1. Register as a Marketplace vendor. -1. List your application, using the application descriptor URL. +1. List your application using the application descriptor URL. - Your manifest file is located at: `https://your.domain/your-path/-/jira_connect/app_descriptor.json` - - GitLab recommends you list your application as `private`, because public + - We recommend you list your application as `private`, because public applications can be viewed and installed by any user. 1. Generate test license tokens for your application. -Review the -[official Atlassian documentation](https://developer.atlassian.com/platform/marketplace/installing-cloud-apps/#creating-the-marketplace-listing) -for details. - NOTE: -Using this method, [updates are automated](#update-the-gitlabcom-for-jira-cloud-app) -the same way as when using our GitLab.com Marketplace listing. +This method uses [automated updates](#update-the-gitlabcom-for-jira-cloud-app) +the same way as our GitLab.com Marketplace listing. ## Troubleshoot GitLab.com for Jira Cloud app -The GitLab.com for Jira Cloud app uses an iframe to add namespaces on the -settings page. Some browsers block cross-site cookies, which can lead to a -message saying that the user needs to log in on GitLab.com even though the user -is already logged in. +### Browser displays sign-in message when already signed in + +You might get the following message prompting you to sign in to GitLab.com +when you're already signed in: + +```plaintext +You need to sign in or sign up before continuing. +``` -> "You need to sign in or sign up before continuing." +GitLab.com for Jira Cloud app uses an iframe to add namespaces on the +settings page. Some browsers block cross-site cookies, which can lead to this issue. -In this case, use [Firefox](https://www.mozilla.org/en-US/firefox/), [Google Chrome](https://www.google.com/chrome/), or enable cross-site cookies in your browser. +To resolve this issue, use [Firefox](https://www.mozilla.org/en-US/firefox/), +[Google Chrome](https://www.google.com/chrome/), or enable cross-site cookies in your browser. |