diff options
Diffstat (limited to 'doc/integration/jira')
| -rw-r--r-- | doc/integration/jira/configure.md | 84 | ||||
| -rw-r--r-- | doc/integration/jira/connect-app.md | 49 | ||||
| -rw-r--r-- | doc/integration/jira/dvcs/index.md | 28 | ||||
| -rw-r--r-- | doc/integration/jira/dvcs/troubleshooting.md | 4 | ||||
| -rw-r--r-- | doc/integration/jira/issues.md | 30 | ||||
| -rw-r--r-- | doc/integration/jira/jira_server_configuration.md | 77 | ||||
| -rw-r--r-- | doc/integration/jira/troubleshooting.md | 2 |
7 files changed, 140 insertions, 134 deletions
diff --git a/doc/integration/jira/configure.md b/doc/integration/jira/configure.md index 3f3511c3838..89afa998431 100644 --- a/doc/integration/jira/configure.md +++ b/doc/integration/jira/configure.md @@ -10,6 +10,8 @@ The Jira issue integration connects one or more GitLab projects to a Jira instan ## Configure the integration +> Authentication with Jira personal access tokens was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/8222) in GitLab 16.0. + Prerequisites: - Your GitLab installation must not use a [relative URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configure-a-relative-url-for-gitlab). @@ -17,55 +19,51 @@ Prerequisites: the email address you used to create the token. - **For Jira Data Center or Jira Server**, you must have one of the following: - [Jira username and password](jira_server_configuration.md). - - Jira personal access token. + - Jira personal access token (GitLab 16.0 and later). You can enable the Jira issue integration by configuring your project settings in GitLab. -You can also configure these settings at the: - -- [Group level](../../user/admin_area/settings/project_integration_management.md#manage-group-level-default-settings-for-a-project-integration) -- [Instance level](../../user/admin_area/settings/project_integration_management.md#manage-instance-level-default-settings-for-a-project-integration) for self-managed GitLab +You can configure these settings at the [group level](../../user/admin_area/settings/project_integration_management.md#manage-group-level-default-settings-for-a-project-integration) or at the [instance level](../../user/admin_area/settings/project_integration_management.md#manage-instance-level-default-settings-for-a-project-integration) for self-managed GitLab. To configure your project settings in GitLab: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Jira**. -1. Select **Enable integration**. -1. Select **Trigger** actions. Your choice determines whether a mention of Jira issue - (in a GitLab commit, merge request, or both) creates a cross-link in Jira back to GitLab. -1. To comment in the Jira issue when a **Trigger** action is made in GitLab, select - **Enable comments**. -1. To transition Jira issues when a - [closing reference](../../user/project/issues/managing_issues.md#closing-issues-automatically) - is made in GitLab, select **Enable Jira transitions**. -1. Provide Jira configuration information: +1. In **Enable integration**, select the **Active** checkbox. +1. Provide connection details: - **Web URL**: Base URL for the Jira instance web interface you're linking to this GitLab project (for example, `https://jira.example.com`). - **Jira API URL**: Base URL for the Jira instance API (for example, `https://jira-api.example.com`). If this URL is not set, the **Web URL** value is used by default. For Jira Cloud, leave **Jira API URL** blank. - - **Authentication type**: From the dropdown list, select: - - **Basic** - - **Jira personal access token (Jira Data Center and Jira Server only)** - - **Email or username** (relevant to **Basic** authentication only): - - For Jira Cloud, enter an email. - - For Jira Data Center or Jira Server, enter a username. - - **New API token, password, or Jira personal access token**: - - For **Basic** authentication: - - For Jira Cloud, enter an API token. - - For Jira Data Center or Jira Server, enter a password. - - For **Jira personal access token** authentication, enter a personal access token. -1. To enable users to [view Jira issues](issues.md#view-jira-issues) inside the GitLab project, select **Enable Jira issues** and - enter a Jira project key. - - You can display issues only from a single Jira project in a given GitLab project. + - **Authentication method**: + - **Basic**: + - **Email or username**: + - For Jira Cloud, enter an email. + - For Jira Data Center or Jira Server, enter a username. + - **API token or password**: + - For Jira Cloud, enter an API token. + - For Jira Data Center or Jira Server, enter a password. + - **Jira personal access token** (only available for Jira Data Center and Jira Server): Enter a personal access token. +1. Provide trigger settings: + - Select **Commit**, **Merge request**, or both as triggers. When you mention a Jira issue ID in GitLab, + GitLab links to that issue. + - To add a comment to the Jira issue that links back to GitLab, select the + **Enable comments** checkbox and the information that the comment displays. + - To [transition Jira issues automatically](../../user/project/issues/managing_issues.md#closing-issues-automatically) in GitLab, + select the **Enable Jira transitions** checkbox. +1. In the **Jira issue matching** section: + - For **Jira issue regex**, [enter a regex pattern](issues.md#use-regular-expression). + - For **Jira issue prefix**, [enter a prefix](issues.md#use-a-prefix). +1. In the **Issues** section: + - To [view Jira issues](issues.md#view-jira-issues) in a GitLab project, select the **Enable Jira issues** checkbox and + enter a Jira project key. You can only view issues from a single Jira project in a GitLab project. WARNING: - If you enable Jira issues with this setting, all users with access to this GitLab project - can view all issues from the specified Jira project. + When you enable this setting, all users with access to that GitLab project + can view all issues from the Jira project you've specified. -1. To enable [issue creation for vulnerabilities](../../user/application_security/vulnerabilities/index.md#create-a-jira-issue-for-a-vulnerability), select **Enable Jira issue creation from vulnerabilities**. -1. Select the **Jira issue type**. If the dropdown list is empty, select **Refresh** (**{retry}**) and try again. -1. To verify the Jira connection is working, select **Test settings**. + - To [create Jira issues for vulnerabilities](../../user/application_security/vulnerabilities/index.md#create-a-jira-issue-for-a-vulnerability), select the **Enable Jira issue creation from vulnerabilities** checkbox. +1. Optional. Select **Test settings**. 1. Select **Save changes**. Your GitLab project can now interact with all Jira projects in your instance, and the project @@ -77,7 +75,7 @@ To configure the Jira issue integration for Jira Cloud, you must have a Jira Clo To create a Jira Cloud API token: 1. Sign in to [Atlassian](https://id.atlassian.com/manage-profile/security/api-tokens) - from an account with **write** access to Jira projects. + from an account with write access to Jira projects. The link opens the **API tokens** page. Alternatively, from your Atlassian profile, select **Account Settings > Security > Create and manage API tokens**. @@ -85,20 +83,20 @@ To create a Jira Cloud API token: 1. Select **Create API token**. 1. In the dialog, enter a label for your token and select **Create**. -To copy the API token, select **Copy** and paste the token somewhere safe. +To copy the API token, select **Copy**. ## Migrate from Jira Server to Jira Cloud in GitLab To migrate from Jira Server to Jira Cloud in GitLab and maintain your Jira integration: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Jira**. 1. In **Web URL**, enter the new Jira site URL (for example, `https://myjirasite.atlassian.net`). -1. In **Username or Email**, enter the username or email registered on your Jira profile. +1. In **Email or username**, enter the email registered on your Jira profile. 1. [Create a Jira Cloud API token](#create-a-jira-cloud-api-token), and copy the token value. -1. In **Password or API token**, paste the API token value. -1. Optional. Select **Test settings** to check if the connection is working. +1. In **API token or password**, paste the API token value. +1. Optional. Select **Test settings**. 1. Select **Save changes**. To update existing Jira issue references in GitLab to use the new Jira site URL, you must [invalidate the Markdown cache](../../administration/invalidate_markdown_cache.md#invalidate-the-cache). diff --git a/doc/integration/jira/connect-app.md b/doc/integration/jira/connect-app.md index e60eeb8fba1..67f51a6f472 100644 --- a/doc/integration/jira/connect-app.md +++ b/doc/integration/jira/connect-app.md @@ -20,6 +20,8 @@ If you use Jira Data Center or Jira Server, use the [Jira DVCS connector](dvcs/i ## Install the GitLab for Jira Cloud app **(FREE SAAS)** +> Link groups feature [renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/331432) from Add namespace in GitLab 16.1. + Prerequisites: - You must have at least the Maintainer role for the GitLab group. @@ -35,7 +37,7 @@ To install the GitLab for Jira Cloud app: 1. To go to the configurations page, select **Get started**. You can always access this page in **Jira Settings > Apps > Manage apps**. -1. For a list of groups to link, select **Add namespace**. +1. For a list of groups to link, select **Link groups**. 1. To link to a group, select **Link**. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> @@ -50,11 +52,9 @@ After you add a group, the following data is synced to Jira for all projects in ## Update the GitLab 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). +Most updates to the app are automatic. For more information, see the +[Atlassian documentation](https://developer.atlassian.com/platform/marketplace/upgrading-and-versioning-cloud-apps/). +If the app requires additional permissions, [you must manually approve the update in Jira](https://developer.atlassian.com/platform/marketplace/upgrading-and-versioning-cloud-apps/#changes-that-require-manual-customer-approval). ## Set up OAuth authentication for self-managed instances **(FREE SELF)** @@ -68,8 +68,9 @@ You must enable OAuth authentication to: To create an OAuth application: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Applications** (`/admin/applications`). +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **Applications**. 1. Select **New application**. 1. In **Redirect URI**: - If you're installing the app from the official marketplace listing, enter `https://gitlab.com/-/jira_connect/oauth_callbacks`. @@ -78,7 +79,7 @@ To create an OAuth application: 1. In **Scopes**, select the `api` checkbox only. 1. Select **Save application**. 1. Copy the **Application ID** value. -1. On the left sidebar, select **Settings > General** (`/admin/application_settings/general`). +1. On the left sidebar, select **Settings > General**. 1. Expand **GitLab for Jira App**. 1. Paste the **Application ID** value into **Jira Connect Application ID**. 1. Select **Save changes**. @@ -105,7 +106,11 @@ To create branches from Jira Cloud, [install the app manually](#install-the-gitl - The instance must be publicly available. - The instance must be on GitLab version 15.7 or later. - You must set up [OAuth authentication](#set-up-oauth-authentication-for-self-managed-instances). -- Your network must allow inbound and outbound connections between GitLab and Jira. +- Your network must allow inbound and outbound connections between GitLab and Jira. For self-managed instances that are behind a + firewall and cannot be directly accessed from the internet, you can: + - Open your firewall and only allow inbound traffic from [Atlassian IP addresses](https://support.atlassian.com/organization-administration/docs/ip-addresses-and-domains-for-atlassian-cloud-products/#Outgoing-Connections). + - Set up an internet-facing reverse proxy in front of your self-managed instance. To secure this proxy further, only allow inbound + traffic from [Atlassian IP addresses](https://support.atlassian.com/organization-administration/docs/ip-addresses-and-domains-for-atlassian-cloud-products/#Outgoing-Connections). ### Set up your instance @@ -113,8 +118,9 @@ To create branches from Jira Cloud, [install the app manually](#install-the-gitl To set up your self-managed instance for the GitLab for Jira Cloud app in GitLab 15.7 and later: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General** (`/admin/application_settings/general`). +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **Settings > General**. 1. Expand **GitLab for Jira App**. 1. In **Jira Connect Proxy URL**, enter `https://gitlab.com`. 1. Select **Save changes**. @@ -207,8 +213,9 @@ You might want to use a proxy if you're managing multiple GitLab instances but o To configure your GitLab instance to serve as a proxy: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General** (`/admin/application_settings/general`). +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **Settings > General**. 1. Expand **GitLab for Jira App**. 1. Select **Enable public key storage**. 1. Select **Save changes**. @@ -276,8 +283,9 @@ To resolve this issue, disable the **Jira Connect Proxy URL** setting. - In GitLab 15.8 and later: - 1. On the top bar, select **Main menu > Admin**. - 1. On the left sidebar, select **Settings > General** (`/admin/application_settings/general`). + 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. Select **Admin Area**. + 1. On the left sidebar, select **Settings > General**. 1. Expand **GitLab for Jira App**. 1. Clear the **Jira Connect Proxy URL** text box. 1. Select **Save changes**. @@ -306,14 +314,9 @@ To resolve this issue on GitLab self-managed, follow one of the solutions below, - In all GitLab versions: - Re-install the GitLab for Jira Cloud app. This method might remove all synced data from the Jira development panel. -### `Failed to update GitLab version` error when setting up the GitLab for Jira Cloud app for self-managed instances +### `Failed to update the GitLab instance` for self-managed instances -When you set up the GitLab for Jira Cloud app, you might get the following message after you enter your -self-managed instance URL: - -```plaintext -Failed to update GitLab version. Please try again. -``` +When you set up the GitLab for Jira Cloud app, you might get a `Failed to update the GitLab instance` error after you enter your self-managed instance URL. To resolve this issue, ensure all prerequisites for your installation method have been met: diff --git a/doc/integration/jira/dvcs/index.md b/doc/integration/jira/dvcs/index.md index 0406fef3f1e..3ebbc9a921d 100644 --- a/doc/integration/jira/dvcs/index.md +++ b/doc/integration/jira/dvcs/index.md @@ -49,16 +49,14 @@ To create a GitLab application for DVCS: To configure Jira for DVCS: -1. Go to your DVCS account. **For Jira Server**, select **Settings (gear) > Applications > DVCS accounts**. -1. To create a new integration, for **Host**, select **GitLab** or **GitLab Self-Managed**. -1. For **Team or User Account**, enter the relative path of a top-level GitLab group that [the GitLab user](#create-a-gitlab-application-for-dvcs) can access. -1. In the **Host URL** text box, enter the appropriate URL. - Replace `<gitlab.example.com>` with your GitLab instance domain. - Use `https://<gitlab.example.com>`. -1. For **Client ID**, use the [**Application ID** value](#create-a-gitlab-application-for-dvcs). -1. For **Client Secret**, use the [**Secret** value](#create-a-gitlab-application-for-dvcs). -1. Ensure that all other checkboxes are selected. -1. To create the DVCS account, select **Add**, then **Continue**. +1. On the top bar, in the upper-right corner, select **Administration** (**{settings}**) > **Applications**. +1. On the left sidebar, select **DVCS accounts**. +1. From the **Host** dropdown list, select **GitLab** or **GitLab Self-Managed**. +1. For **Team or User Account**, enter the relative path of a [top-level GitLab group](#create-a-gitlab-application-for-dvcs) the GitLab user can access. +1. For **Host URL**, enter the domain of your GitLab instance. +1. From the **Client Configuration** dropdown list, select the [application link](#create-a-gitlab-application-for-dvcs) you've created. +1. Optional. Select or clear the **Auto Link New Repositories** and **Enable Smart Commits** checkboxes. +1. Select **Add**, then **Continue**. Jira redirects to GitLab where you have to confirm the authorization. GitLab then redirects back to Jira where the synced projects are displayed in the new account. The initial sync takes a few minutes. @@ -72,6 +70,10 @@ personal namespaces, repeat the previous steps with additional Jira DVCS account Jira imports commits and branches for GitLab projects every 60 minutes. To refresh the data manually in Jira: 1. Sign in to your Jira instance as the user you configured the integration with. -1. Go to **Settings (gear) > Applications**. -1. Select **DVCS accounts**. -1. In the **Last activity** column, next to the repository you want to refresh, select **Refresh** (**{retry}**). +1. On the top bar, in the upper-right corner, select **Administration** (**{settings}**) > **Applications**. +1. On the left sidebar, select **DVCS accounts**. +1. To refresh one or more repositories in a DVCS account: + - **For all repositories**, next to the account, select the ellipsis (**{ellipsis_h}**) > **Refresh repositories**. + - **For a single repository**: + 1. Select the account. + 1. Hover over the repository you want to refresh, and in the **Last activity** column, select **Click to sync repository** (**{retry}**). diff --git a/doc/integration/jira/dvcs/troubleshooting.md b/doc/integration/jira/dvcs/troubleshooting.md index 541c743b609..31038526d63 100644 --- a/doc/integration/jira/dvcs/troubleshooting.md +++ b/doc/integration/jira/dvcs/troubleshooting.md @@ -137,7 +137,7 @@ In the example above, the merge requests feature is disabled. To resolve the issue, enable the relevant feature: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. On the left sidebar, select **Settings > General**. 1. Expand **Visibility, project features, permissions**. 1. Use the toggles to enable the features as needed. @@ -146,7 +146,7 @@ To resolve the issue, enable the relevant feature: To find webhook logs in a DVCS-linked project: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. On the left sidebar, select **Settings > Webhooks**. 1. Scroll down to **Project Hooks**. 1. Next to the log that points to your Jira instance, select **Edit**. diff --git a/doc/integration/jira/issues.md b/doc/integration/jira/issues.md index 086d478ac15..7ed9d3ab329 100644 --- a/doc/integration/jira/issues.md +++ b/doc/integration/jira/issues.md @@ -27,7 +27,7 @@ git commit -m "GIT-1 this is a test commit" GitLab adds to that Jira issue: -- A reference in the **Web links** section +- A reference in the **Web links** section. - A comment in the **Activity** section that follows this format: ```plaintext @@ -41,9 +41,9 @@ GitLab adds to that Jira issue: - `COMMENTLINK`: Link to where the Jira issue is mentioned. - `ENTITY_TITLE`: Title of the GitLab commit (first line), issue, or merge request. -Only a single cross-reference comment appears in Jira per GitLab issue, merge request, or commit. +Only a single cross-reference appears in Jira per GitLab issue, merge request, or commit. For example, multiple comments on a GitLab merge request that reference a Jira issue -create only a single cross-reference comment back to that merge request in Jira. +create only a single cross-reference back to that merge request in Jira. You can [disable comments](#disable-comments-on-jira-issues) on issues. @@ -55,8 +55,8 @@ You can [disable comments](#disable-comments-on-jira-issues) on issues. With this integration, you can prevent merge requests from being merged if they do not refer to a Jira issue. To enable this feature: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Merge requests**. 1. In the **Merge checks** section, select **Require an associated issue from Jira**. 1. Select **Save**. @@ -79,8 +79,8 @@ When you don't configure custom rules, the [default behavior](https://gitlab.com To define a regex pattern for Jira issue keys: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Jira**. 1. Go to the **Jira issue matching** section. 1. In the **Jira issue regex** text box, enter a regex pattern. @@ -92,8 +92,8 @@ For more information, see the [Atlassian documentation](https://confluence.atlas To define a prefix for Jira issue keys: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Jira**. 1. Go to the **Jira issue matching** section. 1. In the **Jira issue prefix** text box, enter a prefix. @@ -138,8 +138,8 @@ provided your GitLab administrator [has configured the integration](configure.md To view Jira issues: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Issues > Jira issues**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Plan > Jira issues**. The issues are sorted by **Created date** by default, with the most recently created issues listed at the top. @@ -173,10 +173,6 @@ of these filters: Enhancements to use these filters through the user interface [are planned](https://gitlab.com/groups/gitlab-org/-/epics/3622). -## Create a Jira issue for a vulnerability **(ULTIMATE)** - -You can create a Jira issue for a vulnerability from a [Vulnerability Page](../../user/application_security/vulnerabilities/index.md#create-a-jira-issue-for-a-vulnerability). - ## Automatic issue transitions > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55773) in GitLab 13.11. @@ -217,3 +213,7 @@ adding a comment to the Jira issue: 1. Refer to the [Configure GitLab](configure.md) instructions. 1. Clear the **Enable comments** checkbox. + +## Related topics + +- [Create a Jira issue for a vulnerability](../../user/application_security/vulnerabilities/index.md#create-a-jira-issue-for-a-vulnerability) diff --git a/doc/integration/jira/jira_server_configuration.md b/doc/integration/jira/jira_server_configuration.md index c840e1ebde5..672df5d615f 100644 --- a/doc/integration/jira/jira_server_configuration.md +++ b/doc/integration/jira/jira_server_configuration.md @@ -4,55 +4,55 @@ group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Jira Server credentials **(FREE)** +# Tutorial: Create Jira credentials **(FREE)** -To [integrate Jira with GitLab](configure.md), you should create a separate Jira user account for your Jira projects -to access projects in GitLab. This Jira user account must have write access to your Jira projects. -To create the credentials: +This tutorial shows you how to create Jira credentials. You can use your new Jira credentials to +configure the [Jira issue integration](configure.md) in GitLab for Jira Data Center or Jira Server. -1. [Create a Jira Server user](#create-a-jira-server-user). -1. [Create a Jira Server group for the user](#create-a-jira-server-group-for-the-user). +To create Jira credentials, here's what we're going to do: + +1. [Create a Jira user](#create-a-jira-user). +1. [Create a Jira group for the user](#create-a-jira-group-for-the-user). 1. [Create a permission scheme for the group](#create-a-permission-scheme-for-the-group). -Alternatively, you can use an existing Jira user account, provided the user belongs to a Jira group that -has been granted the **Administer Projects** [permission scheme](#create-a-permission-scheme-for-the-group). +Prerequisite: + +- You must have administrator access to the Jira instance. + +## Create a Jira user -After you select a Jira user account, [configure the integration](configure.md#configure-the-integration) in GitLab to use the account. +To create a Jira user: -## Create a Jira Server user +1. Sign in to your Jira instance as an administrator. +1. On the top bar, in the upper-right corner, select **Administration** (**{settings}**) > **User management**. +1. [Create a new user account](https://confluence.atlassian.com/adminjiraserver/create-edit-or-remove-a-user-938847025.html#Create,edit,orremoveauser-CreateusersmanuallyinJira) with write access to your Jira projects. -To create a Jira Server user: + Alternatively, you can use an existing user account, provided the user belongs to a Jira group that has been granted + the **Administer Projects** [permission scheme](#create-a-permission-scheme-for-the-group). -1. Sign in to your Jira instance as a Jira administrator. -1. On the top bar, in the upper-right corner, select the gear icon, then - select **User Management**. -1. [Create a new user account manually](https://confluence.atlassian.com/adminjiraserver/create-edit-or-remove-a-user-938847025.html#Create,edit,orremoveauser-CreateusersmanuallyinJira) with write access to - projects in Jira. - - **Email address**: You should use a valid email address. - - **Username**: Set the username to `gitlab`. - - **Password**: You must set a password because the Jira issue integration does not - support SSO such as SAML. + - In **Email address**, enter a valid email address. + - In **Username**, enter `gitlab`. + - In **Password**, enter a password (the Jira issue integration does not support SSO such as SAML). 1. Select **Create user**. Now that you've created a user named `gitlab`, it's time to create a group for the user. -## Create a Jira Server group for the user +## Create a Jira group for the user -To create a Jira Server group for the user: +To create a Jira group for the user: -1. Sign in to your Jira instance as a Jira administrator. -1. On the top bar, in the upper-right corner, select the gear icon, then - select **User Management**. +1. Sign in to your Jira instance as an administrator. +1. On the top bar, in the upper-right corner, select **Administration** (**{settings}**) > **User management**. 1. On the left sidebar, select **Groups**. -1. In the **Add group** section, enter a **Name** for the group (for example, +1. In the **Add group** section, enter a name for the group (for example, `gitlab-developers`), then select **Add group**. -1. To add the `gitlab` user to the `gitlab-developers` group, select **Edit members**. +1. To add the `gitlab` user to the new `gitlab-developers` group, select **Edit members**. The `gitlab-developers` group appears as a selected group. <!-- vale gitlab.BadPlurals = NO --> 1. In the **Add members to selected group(s)** section, enter `gitlab`. +<!-- vale gitlab.BadPlurals = YES --> 1. Select **Add selected users**. The `gitlab` user appears as a group member. -<!-- vale gitlab.BadPlurals = YES --> Now that you've added the `gitlab` user to a new group named `gitlab-developers`, it's time to create a permission scheme for the group. @@ -61,15 +61,18 @@ it's time to create a permission scheme for the group. To create a permission scheme for the group: -1. Sign in to your Jira instance as a Jira administrator. -1. On the top bar, in the upper-right corner, select the gear icon, then - select **Issues**. -1. On the left sidebar, select **Permission Schemes**. -1. Select **Add Permission Scheme**, enter a **Name** and (optionally) a - **Description**, then select **Add**. -1. In the permissions scheme list, locate your new permissions scheme, and - select **Permissions**. +1. Sign in to your Jira instance as an administrator. +1. On the top bar, in the upper-right corner, select **Administration** (**{settings}**) > **Issues**. +1. On the left sidebar, select **Permission schemes**. +1. Select **Add permission scheme**. +1. In the **Add permission scheme** dialog: + - Enter a name for the scheme. + - Optional. Enter a description for the scheme. +1. Select **Add**. +1. On the **Permission schemes** page, in the **Actions** column, select **Permissions** for the new scheme. 1. Next to **Administer Projects**, select **Edit**. +1. In the **Grant permission** dialog, for **Granted to**, select **Group**. 1. From the **Group** dropdown list, select `gitlab-developers`, then select **Grant**. -You need the new Jira username and password when you [configure the integration](configure.md#configure-the-integration) in GitLab. +You've done it! You can now use your new Jira username and password to configure the +[Jira issue integration](configure.md) in GitLab for Jira Data Center or Jira Server. diff --git a/doc/integration/jira/troubleshooting.md b/doc/integration/jira/troubleshooting.md index 586f09be751..d592455788d 100644 --- a/doc/integration/jira/troubleshooting.md +++ b/doc/integration/jira/troubleshooting.md @@ -16,7 +16,7 @@ set up for the [Jira integration](configure.md) has permission to: - Post comments on a Jira issue. - Transition the Jira issue. -Jira issue references and update comments do not work if the GitLab issue tracker is disabled. +Jira issue references and update comments do not work if the [GitLab issue tracker](../../integration/external-issue-tracker.md) is disabled. If you [restrict IP addresses for Jira access](https://support.atlassian.com/security-and-access-policies/docs/specify-ip-addresses-for-product-access/), make sure you add your self-managed IP addresses or [GitLab.com IP range](../../user/gitlab_com/index.md#ip-range) to the allowlist in Jira. |