diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-09-20 13:18:24 +0000 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-09-20 13:18:24 +0000 |
commit | 0653e08efd039a5905f3fa4f6e9cef9f5d2f799c (patch) | |
tree | 4dcc884cf6d81db44adae4aa99f8ec1233a41f55 /doc/integration/jira | |
parent | 744144d28e3e7fddc117924fef88de5d9674fe4c (diff) | |
download | gitlab-ce-0653e08efd039a5905f3fa4f6e9cef9f5d2f799c.tar.gz |
Add latest changes from gitlab-org/gitlab@14-3-stable-eev14.3.0-rc42
Diffstat (limited to 'doc/integration/jira')
-rw-r--r-- | doc/integration/jira/configure.md | 2 | ||||
-rw-r--r-- | doc/integration/jira/connect-app.md | 28 | ||||
-rw-r--r-- | doc/integration/jira/development_panel.md | 8 | ||||
-rw-r--r-- | doc/integration/jira/dvcs.md | 44 | ||||
-rw-r--r-- | doc/integration/jira/index.md | 13 | ||||
-rw-r--r-- | doc/integration/jira/jira_cloud_configuration.md | 6 | ||||
-rw-r--r-- | doc/integration/jira/jira_server_configuration.md | 2 |
7 files changed, 58 insertions, 45 deletions
diff --git a/doc/integration/jira/configure.md b/doc/integration/jira/configure.md index b11f367258d..d4e5a1bfca1 100644 --- a/doc/integration/jira/configure.md +++ b/doc/integration/jira/configure.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Configure the Jira integration in GitLab +# Configure the Jira integration in GitLab **(FREE)** You can set up the [Jira integration](index.md#jira-integration) by configuring your project settings in GitLab. diff --git a/doc/integration/jira/connect-app.md b/doc/integration/jira/connect-app.md index e32bd4559f9..7d32c080fff 100644 --- a/doc/integration/jira/connect-app.md +++ b/doc/integration/jira/connect-app.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w NOTE: Only Jira users with administrator level access are able to install or configure -the GitLab app for Jira Cloud. +the GitLab.com for Jira Cloud app. ## GitLab.com for Jira Cloud app **(FREE SAAS)** @@ -60,6 +60,14 @@ After a namespace is added: Support for syncing past branch and commit data is tracked [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/263240). +## Update the GitLab.com for Jira Cloud app + +Most updates to the app are fully automated and don't require any user interaction. See the +[Atlassian Marketplace documentation](https://developer.atlassian.com/platform/marketplace/upgrading-and-versioning-cloud-apps/) +for details. + +If the app requires additional permissions, [the update must first be manually approved in Jira](https://developer.atlassian.com/platform/marketplace/upgrading-and-versioning-cloud-apps/#changes-that-require-manual-customer-approval). + ## Install the GitLab.com for Jira Cloud app for self-managed instances **(FREE SELF)** If your GitLab instance is self-managed, you must follow some @@ -78,10 +86,10 @@ self-managed GitLab instances with Jira Cloud, you can either: You can configure your Atlassian Cloud instance to allow you to install applications from outside the Marketplace, which allows you to install the application: -1. Sign in to your Jira instance as a user with administrator permissions. +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 [Administrator](../../user/permissions.md) permissions. +1. Sign in to your GitLab application as a user with an [Administrator](../../user/permissions.md) role. 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**: @@ -103,13 +111,13 @@ The **GitLab.com for Jira Cloud** app now displays under **Manage apps**. You ca click **Get started** to open the configuration page rendered from your GitLab instance. NOTE: -If you make changes to the application descriptor, you must uninstall, then reinstall, the +If a GitLab update makes changes to the application descriptor, you must uninstall, then reinstall, the application. ### Create a Marketplace listing **(FREE SELF)** If you prefer to not use development mode on your Jira instance, you can create -your own Marketplace listing for your instance, which enables your application +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 @@ -127,11 +135,15 @@ Review the for details. NOTE: -DVCS means distributed version control system. +Using this method, [updates are automated](#update-the-gitlabcom-for-jira-cloud-app) +the same way as when using our GitLab.com Marketplace listing. -## Troubleshooting GitLab.com for Jira Cloud app +## 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. +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. > "You need to sign in or sign up before continuing." diff --git a/doc/integration/jira/development_panel.md b/doc/integration/jira/development_panel.md index c8ea224f18e..5a2ce8a0a75 100644 --- a/doc/integration/jira/development_panel.md +++ b/doc/integration/jira/development_panel.md @@ -65,11 +65,11 @@ For an overview of how to configure Jira Development panel integration, see [Agile Management - GitLab Jira Development panel integration](https://www.youtube.com/watch?v=VjVTOmMl85M). To simplify administration, we recommend that a GitLab group maintainer or group owner -(or instance administrator in the case of self-managed GitLab) set up the integration. +(or, if possible, instance administrator in the case of self-managed GitLab) set up the integration. | Jira usage | GitLab.com customers need | GitLab self-managed customers need | |------------|---------------------------|------------------------------------| -| [Atlassian cloud](https://www.atlassian.com/cloud) | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview) application installed from the [Atlassian Marketplace](https://marketplace.atlassian.com). This offers real-time sync between GitLab and Jira. For more information, see the documentation for the [GitLab.com for Jira Cloud app](connect-app.md). | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview), using a workaround process. See the documentation for [installing the GitLab Jira Cloud application for self-managed instances](connect-app.md#install-the-gitlabcom-for-jira-cloud-app-for-self-managed-instances) for more information. | +| [Atlassian cloud](https://www.atlassian.com/cloud) | The [GitLab.com for Jira Cloud app](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview) installed from the [Atlassian Marketplace](https://marketplace.atlassian.com). This offers real-time sync between GitLab.com and Jira. For more information, see the documentation for the [GitLab.com for Jira Cloud app](connect-app.md). | The [GitLab.com for Jira Cloud app](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview), using a workaround process. See the documentation for [installing the GitLab.com for Jira Cloud app for self-managed instances](connect-app.md#install-the-gitlabcom-for-jira-cloud-app-for-self-managed-instances) for more information. | | Your own server | The [Jira DVCS (distributed version control system) connector](dvcs.md). This syncs data hourly. | The [Jira DVCS Connector](dvcs.md). | Each GitLab project can be configured to connect to an entire Jira instance. That means after @@ -89,10 +89,6 @@ This integration is not supported on GitLab instances under a [relative URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab). For example, `http://example.com/gitlab`. -## Related topics - -- [Using Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html) in Jira - ## Troubleshooting ### Cookies for Oracle's Access Manager diff --git a/doc/integration/jira/dvcs.md b/doc/integration/jira/dvcs.md index 7d97312757e..664a0361da4 100644 --- a/doc/integration/jira/dvcs.md +++ b/doc/integration/jira/dvcs.md @@ -8,15 +8,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w Use the Jira DVCS (distributed version control system) connector if you self-host your Jira instance, and you want to sync information -between GitLab and Jira. If you use Jira Cloud and GitLab.com, you should use the -[GitLab.com for Jira Cloud app](connect-app.md) unless you specifically need the DVCS connector. +between GitLab and Jira. If you use Jira Cloud, you should use the +[GitLab.com for Jira Cloud app](connect-app.md) unless you specifically need the +DVCS connector. When you configure the Jira DVCS connector, make sure your GitLab and Jira instances are accessible. - **Self-managed GitLab**: Your GitLab instance must be accessible by Jira. -- **Jira Cloud**: Your instance must be accessible through the internet. - **Jira Server**: Your network must allow access to your instance. +- **Jira Cloud**: Your instance must be accessible through the internet. ## Smart commits @@ -61,25 +62,25 @@ you can still perform multiple actions in a single commit: ## Configure a GitLab application for DVCS -We recommend you create and use a `jira` user in GitLab, and use the account only -for integration work. A separate account ensures regular account maintenance does not affect -your integration. +We recommend you create and use a `jira` user in GitLab, and use the account +only for integration work. A separate account ensures regular account +maintenance does not affect your integration. If a `jira` user is not feasible, +you can set up this integration with your own account instead. 1. In GitLab, [create a user](../../user/profile/account/create_accounts.md) for Jira to - use to connect to GitLab. For Jira to access all projects, - a user with [administrator](../../user/permissions.md) permissions must - create the user with administrator permissions. + use to connect to GitLab. This user must be added to each project you want Jira to have access to, + or have an [Administrator](../../user/permissions.md) role to access all projects. 1. Sign in as the `jira` user. 1. In the top right corner, click the account's avatar, and select **Edit profile**. -1. In the left sidebar, select **Applications**. +1. On the left sidebar, select **Applications**. 1. In the **Name** field, enter a descriptive name for the integration, such as `Jira`. 1. In the **Redirect URI** field, enter the URI appropriate for your version of GitLab, replacing `<gitlab.example.com>` with your GitLab instance domain: - *For GitLab versions 13.0 and later* **and** *Jira versions 8.14 and later,* use the generated `Redirect URL` from [Linking GitLab accounts with Jira](https://confluence.atlassian.com/adminjiraserver/linking-gitlab-accounts-1027142272.html). - - *For GitLab versions 13.0 and later* **and** *Jira Cloud,* use `https://<gitlab.example.com>/login/oauth/callback`. - - *For GitLab versions 11.3 and later,* use `https://<gitlab.example.com>/login/oauth/callback`. + - *For GitLab versions 13.0 and later* **and** *Jira Cloud,* use `https://<gitlab.example.com>/login/oauth/callback`. + - *For GitLab versions 11.3 and later* **and** *Jira versions 8.13 and earlier,* use `https://<gitlab.example.com>/login/oauth/callback`. If you use GitLab.com, the URL is `https://gitlab.com/login/oauth/callback`. - *For GitLab versions 11.2 and earlier,* use `https://<gitlab.example.com>/-/jira/login/oauth/callback`. @@ -105,9 +106,9 @@ it completes, refreshes every 60 minutes: - *For Jira versions 8.13 and earlier:* Select **GitHub Enterprise**. 1. For **Team or User Account**, enter either: - *For Jira versions 8.14 and later:* - - The relative path of a top-level GitLab group that you have access to. + - The relative path of a top-level GitLab group that [the GitLab user](#configure-a-gitlab-application-for-dvcs) has access to. - *For Jira versions 8.13 and earlier:* - - The relative path of a top-level GitLab group that you have access to. + - The relative path of a top-level GitLab group that [the GitLab user](#configure-a-gitlab-application-for-dvcs) has access to. - The relative path of your personal namespace. 1. In the **Host URL** field, enter the URI appropriate for your version of GitLab, @@ -141,7 +142,7 @@ can refresh the data manually from the Jira interface: column, select the icon: ![Refresh GitLab information in Jira](img/jira_dev_panel_manual_refresh.png) -## Troubleshooting your DVCS connection +## Troubleshoot your DVCS connection Refer to the items in this section if you're having problems with your DVCS connector. @@ -174,7 +175,8 @@ Error obtaining access token. Cannot access https://gitlab.example.com from Jira must have the appropriate certificate (such as your organization's root certificate) added to it . -Refer to Atlassian's documentation and Atlassian Support for assistance setting up Jira correctly: +Refer to Atlassian's documentation and Atlassian Support for assistance setting +up Jira correctly: - [Add a certificate](https://confluence.atlassian.com/kb/how-to-import-a-public-ssl-certificate-into-a-jvm-867025849.html) to the trust store. @@ -232,9 +234,17 @@ To resolve this issue: [Contact GitLab Support](https://about.gitlab.com/support/) if none of these reasons apply. +### `410 : Gone` error when connecting to Jira + +When you connect to Jira and synchronize repositories, you may receive a `410 : Gone` error. + +This issue occurs when you use the Jira DVCS connector and your integration is configured to use **GitHub Enterprise**. + +For more information and possible fixes, see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/340160). + ### Fix synchronization issues -If Jira displays incorrect information, such as deleted branches, you may need to +If Jira displays incorrect information, such as deleted branches, you may have to resynchronize the information. To do so: 1. In Jira, go to **Jira Administration > Applications > DVCS accounts**. diff --git a/doc/integration/jira/index.md b/doc/integration/jira/index.md index febd9907028..85f99b49c41 100644 --- a/doc/integration/jira/index.md +++ b/doc/integration/jira/index.md @@ -26,9 +26,7 @@ The supported Jira versions are `v6.x`, `v7.x`, and `v8.x`. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Agile Management - GitLab-Jira Basic Integration](https://www.youtube.com/watch?v=fWvwkx5_00E&feature=youtu.be). -To set up the integration, [configure the project settings](configure.md) in GitLab. -You can also configure these settings at a [group level](../../user/admin_area/settings/project_integration_management.md#manage-group-level-default-settings-for-a-project-integration), -and for self-managed GitLab, at an [instance level](../../user/admin_area/settings/project_integration_management.md#manage-instance-level-default-settings-for-a-project-integration). +To set up the integration, [configure the settings](configure.md) in GitLab. ### Jira development panel integration @@ -37,12 +35,9 @@ connects all GitLab projects under a group or personal namespace. When configure relevant GitLab information, including related branches, commits, and merge requests, displays in the [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/). -To set up the Jira development panel integration: - -- *If your installation uses Jira Cloud,* use the - [GitLab for Jira app](connect-app.md). -- *If either your Jira or GitLab installation is self-managed,* use the - [Jira DVCS Connector](dvcs.md). +To set up the Jira development panel integration, use the GitLab.com for Jira Cloud app +or the Jira DVCS (distributed version control system) connector, +[depending on your installation](development_panel.md#configure-the-integration). ### Direct feature comparison diff --git a/doc/integration/jira/jira_cloud_configuration.md b/doc/integration/jira/jira_cloud_configuration.md index e42a102e030..0cfffdb8ba4 100644 --- a/doc/integration/jira/jira_cloud_configuration.md +++ b/doc/integration/jira/jira_cloud_configuration.md @@ -11,10 +11,10 @@ on Atlassian cloud. To create the API token: 1. Sign in to [`id.atlassian.com`](https://id.atlassian.com/manage-profile/security/api-tokens) with your email address. Use an account with *write* access to Jira projects. -1. Go to **Settings > API tokens**. +1. Go to **Settings > Atlassian account settings > Security > Create and manage API tokens**. 1. Select **Create API token** to display a modal window with an API token. -1. To copy the API token, select **Copy to clipboard**, or select **View** and write - down the new API token. You need this value when you +1. In the dialog, enter a label for your token and select **Create**. +1. To copy the API token, select **Copy**, then paste the token somewhere safe. You need this value when you [configure GitLab](configure.md). You need the newly created token, and the email diff --git a/doc/integration/jira/jira_server_configuration.md b/doc/integration/jira/jira_server_configuration.md index 52e7e5e412b..32a8cd430f9 100644 --- a/doc/integration/jira/jira_server_configuration.md +++ b/doc/integration/jira/jira_server_configuration.md @@ -25,7 +25,7 @@ This process creates a user named `gitlab` and adds it to a new group named `git 1. Create a new user account (`gitlab`) with write access to projects in Jira. - **Email address**: Jira requires a valid email address, and sends a verification - email, which you need to set up the password. + email, which is required to set up the password. - **Username**: Jira creates the username by using the email prefix. You can change this username later. - **Password**: You must create a password, because the GitLab integration doesn't |