diff options
Diffstat (limited to 'doc/integration/jira')
| -rw-r--r-- | doc/integration/jira/connect-app.md | 93 | ||||
| -rw-r--r-- | doc/integration/jira/development_panel.md | 7 | ||||
| -rw-r--r-- | doc/integration/jira/dvcs.md | 95 | ||||
| -rw-r--r-- | doc/integration/jira/index.md | 36 | ||||
| -rw-r--r-- | doc/integration/jira/jira_cloud_configuration.md | 15 | ||||
| -rw-r--r-- | doc/integration/jira/jira_server_configuration.md | 30 |
6 files changed, 150 insertions, 126 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. diff --git a/doc/integration/jira/development_panel.md b/doc/integration/jira/development_panel.md index 6fa084ee872..8f66edcffa8 100644 --- a/doc/integration/jira/development_panel.md +++ b/doc/integration/jira/development_panel.md @@ -38,7 +38,7 @@ After the integration is [set up on GitLab and Jira](#configure-the-integration) - Refer to any Jira issue by its ID (in uppercase) in GitLab branch names, commit messages, and merge request titles. - See the linked branches, commits, and merge requests in Jira issues. -- Create GitLab branches from Jira issues ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66032) in GitLab 14.2). +- Create GitLab branches from Jira Cloud issues ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66032) in GitLab 14.2). At this time, merge requests are called "pull requests" in Jira issues. This name may change in a future Jira release. @@ -89,7 +89,10 @@ 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`. -## Troubleshooting +## Troubleshoot the Development Panel + +If you use Jira on your own server, go to the [Atlassian documentation](https://confluence.atlassian.com/jirakb/troubleshoot-the-development-panel-in-jira-server-574685212.html) +for general troubleshooting information. ### Cookies for Oracle's Access Manager diff --git a/doc/integration/jira/dvcs.md b/doc/integration/jira/dvcs.md index 664a0361da4..2b7cc5ff0a6 100644 --- a/doc/integration/jira/dvcs.md +++ b/doc/integration/jira/dvcs.md @@ -19,7 +19,7 @@ are accessible. - **Jira Server**: Your network must allow access to your instance. - **Jira Cloud**: Your instance must be accessible through the internet. -## Smart commits +## Smart Commits When connecting GitLab with Jira with DVCS, you can process your Jira issues using special commands, called @@ -48,17 +48,24 @@ Smart Commits should follow the pattern of: Some examples: -- Adding a comment to a Jira issue: `KEY-123 fixes a bug #comment Bug is fixed.` -- Recording time tracking: `KEY-123 #time 2w 4d 10h 52m Tracking work time.` -- Closing an issue: `KEY-123 #close Closing issue` +- Add a comment to a Jira issue: `KEY-123 fixes a bug #comment Bug is fixed.` +- Record time tracking: `KEY-123 #time 2w 4d 10h 52m Tracking work time.` +- Close an issue: `KEY-123 #close Closing issue` A Smart Commit message must not span more than one line (no carriage returns) but -you can still perform multiple actions in a single commit: +you can still perform multiple actions in a single commit. For example: -- Time tracking, commenting, and transitioning to **Closed**: - `KEY-123 #time 2d 5h #comment Task completed ahead of schedule #close`. -- Commenting, transitioning to **In-progress**, and time tracking: - `KEY-123 #comment started working on the issue #in-progress #time 12d 5h`. +- Add time tracking, add a comment, and transition to **Closed**: + + ```plaintext + KEY-123 #time 2d 5h #comment Task completed ahead of schedule #close + ``` + +- Add a comment, transition to **In-progress**, and add time tracking: + + ```plaintext + KEY-123 #comment started working on the issue #in-progress #time 12d 5h + ``` ## Configure a GitLab application for DVCS @@ -69,9 +76,9 @@ 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. 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. + or be an administrator 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. On the top bar, in the top right corner, select the user's avatar, and select **Edit profile**. 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, @@ -86,9 +93,10 @@ you can set up this integration with your own account instead. `https://<gitlab.example.com>/-/jira/login/oauth/callback`. 1. For **Scopes**, select `api` and clear any other checkboxes. + - The DVCS connector requires a _write-enabled_ `api` scope to automatically create and manage required webhooks. 1. Select **Submit**. -1. GitLab displays the generated **Application ID** - and **Secret** values. Copy these values, as you need them to configure Jira. +1. Copy the **Application ID** and **Secret** values. + You need them to configure Jira. ## Configure Jira for DVCS @@ -96,19 +104,21 @@ Configure this connection when you want to import all GitLab commits and branche for the groups you specify, into Jira. This import takes a few minutes and, after it completes, refreshes every 60 minutes: -1. Ensure you have completed the [GitLab configuration](#configure-a-gitlab-application-for-dvcs). +1. Complete the [GitLab configuration](#configure-a-gitlab-application-for-dvcs). 1. Go to your DVCS accounts: - - *For Jira Server,* go to **Settings (gear) > Applications > DVCS accounts**. - - *For Jira Cloud,* go to **Settings (gear) > Products > DVCS accounts**. + - *For Jira Server,* select **Settings (gear) > Applications > DVCS accounts**. + - *For Jira Cloud,* select **Settings (gear) > Products > DVCS accounts**. 1. To create a new integration, select the appropriate value for **Host**: - *For Jira versions 8.14 and later:* Select **GitLab** or **GitLab Self-Managed**. - - *For Jira versions 8.13 and earlier:* Select **GitHub Enterprise**. + - *For Jira Cloud or 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 [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 [the GitLab user](#configure-a-gitlab-application-for-dvcs) has 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 Cloud or Jira versions 8.13 and earlier:* + - 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, @@ -119,13 +129,13 @@ it completes, refreshes every 60 minutes: 1. For **Client ID**, use the **Application ID** value from the previous section. 1. For **Client Secret**, use the **Secret** value from the previous section. -1. Ensure that the rest of the checkboxes are checked. -1. Select **Add** and then **Continue** to create the DVCS account. -1. Jira redirects to GitLab where you have to confirm the authorization, - and then GitLab redirects back to Jira where you should see the synced - projects show up inside the new account. +1. Ensure that the rest of the checkboxes are selected. +1. To create the DVCS account, select **Add** and then **Continue**. +1. Jira redirects to GitLab where you have to confirm the authorization. + GitLab then redirects back to Jira where the synced + projects should display in the new account. -To connect additional GitLab projects from other GitLab top-level groups, or +To connect additional GitLab projects from other GitLab top-level groups or personal namespaces, repeat the previous steps with additional Jira DVCS accounts. After you configure the integration, read more about [how to test and use it](development_panel.md). @@ -171,9 +181,8 @@ Error obtaining access token. Cannot access https://gitlab.example.com from Jira 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 - must have the appropriate certificate (such as your organization's - root certificate) added to it . + issued by a public certificate authority, add the appropriate certificate + (such as your organization's root certificate) to the Java Truststore on Jira's server. Refer to Atlassian's documentation and Atlassian Support for assistance setting up Jira correctly: @@ -186,8 +195,8 @@ up Jira correctly: - If the integration stops working after upgrading Jira's Java runtime, the `cacerts` Truststore may have been replaced during the upgrade. -- 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`. +- Troubleshoot 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 `SSLPoke` Java class. - Download the class from Atlassian's knowledge base to a directory on Jira's server, such as `/tmp`. - Use the same Java runtime as Jira. - Pass all networking-related parameters that Jira is called with, such as proxy @@ -202,7 +211,7 @@ 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. -### Scope error when connecting Jira via DVCS +### Scope error when connecting to Jira using DVCS ```plaintext The requested scope is invalid, unknown, or malformed. @@ -223,12 +232,12 @@ After you complete the **Add New Account** form in Jira and authorize access, yo encounter these issues: - An `Error! Failed adding the account: [Error retrieving list of repositories]` error. -- An `Account is already integrated with JIRA` error when you click **Try Again**. +- An `Account is already integrated with JIRA` error when you select **Try Again**. - An account is visible in the DVCS accounts view, but no repositories are listed. To resolve this issue: -- If you're using GitLab Free, be sure you're using GitLab 13.4 or later. +- If you're using GitLab Free, ensure you're using GitLab 13.4 or later. - 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). @@ -242,17 +251,17 @@ This issue occurs when you use the Jira DVCS connector and your integration is c For more information and possible fixes, see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/340160). -### Fix synchronization issues +### Synchronization issues 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**. -1. At the account (group or subgroup) level, Jira displays an option to - **Refresh repositories** in the **{ellipsis_h}** (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. - - To complete a *full sync*, shift-click the button. +resynchronize the information: + +1. In Jira, select **Jira Administration > Applications > DVCS accounts**. +1. For the account (group or subgroup), select + **Refresh repositories** from the **{ellipsis_h}** (ellipsis) menu. +1. For each project, next to the **Last activity** date: + - To perform a *soft resync*, select the sync icon. + - To complete a *full sync*, press `Shift` and select the sync icon. For more information, read [Atlassian's documentation](https://support.atlassian.com/jira-cloud-administration/docs/synchronize-jira-cloud-to-bitbucket/). diff --git a/doc/integration/jira/index.md b/doc/integration/jira/index.md index f5f7e8c33fc..3052d85b2cb 100644 --- a/doc/integration/jira/index.md +++ b/doc/integration/jira/index.md @@ -10,7 +10,7 @@ If your organization uses [Jira](https://www.atlassian.com/software/jira) issues you can [migrate your issues from Jira](../../user/project/import/jira.md) and work exclusively in GitLab. However, if you'd like to continue to use Jira, you can integrate it with GitLab. GitLab offers two types of Jira integrations, and you -can use one or both depending on the capabilities you need. It is recommended that you enable both. +can use one or both depending on the capabilities you need. We recommend you enable both. ## Compare integrations @@ -41,7 +41,7 @@ or the Jira DVCS (distributed version control system) connector, ### Direct feature comparison -| Capability | Jira integration | Jira Development panel integration | +| Capability | Jira integration | Jira development panel integration | |-|-|-| | Mention a Jira issue ID in a GitLab commit or merge request, and a link to the Jira issue is created. | Yes. | No. | | Mention a Jira issue ID in GitLab and the Jira issue shows the GitLab issue or merge request. | Yes. A Jira comment with the GitLab issue or MR title links to GitLab. The first mention is also added to the Jira issue under **Web links**. | Yes, in the issue's [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/). | @@ -55,15 +55,15 @@ or the Jira DVCS (distributed version control system) connector, ## Authentication in Jira -The process for configuring Jira depends on whether you host Jira on your own server or on +The authentication method in Jira depends on whether you host Jira on your own server or on [Atlassian cloud](https://www.atlassian.com/cloud): - **Jira Server** supports basic authentication. When connecting, a **username and password** are - required. Connecting to Jira Server via CAS is not possible. For more information, read + required. Connecting to Jira Server using the Central Authentication Service (CAS) is not possible. For more information, read how to [set up a user in Jira Server](jira_server_configuration.md). - **Jira on Atlassian cloud** supports authentication through an API token. When connecting to Jira on Atlassian cloud, an email and API token are required. For more information, read - [set up a user in Jira on Atlassian cloud](jira_cloud_configuration.md). + [create an API token for Jira in Atlassian cloud](jira_cloud_configuration.md). ## Privacy considerations @@ -72,11 +72,16 @@ actions in GitLab issues and merge requests linked to a Jira issue leak informat about the private project to non-administrator Jira users. If your installation uses Jira Cloud, you can use the [GitLab.com for Jira Cloud app](connect-app.md) to avoid this risk. +## Third-party Jira integrations + +Developers have built several third-party Jira integrations for GitLab that are +listed on the [Atlassian Marketplace](https://marketplace.atlassian.com/search?product=jira&query=gitlab). + ## Troubleshooting If these features do not work as expected, it is likely due to a problem with the way the integration settings were configured. -### GitLab is unable to comment on a Jira issue +### GitLab cannot comment on a Jira issue If GitLab cannot comment on Jira issues, make sure the Jira user you set up for the integration has permission to: @@ -86,14 +91,16 @@ set up for the integration has permission to: Jira issue references and update comments do not work if the GitLab issue tracker is disabled. -### GitLab is unable to close a Jira issue +### GitLab cannot close a Jira issue + +If GitLab cannot close a Jira issue: -Make sure the `Transition ID` you set in the Jira settings matches the one -your project needs to close an issue. +- Make sure the `Transition ID` you set in the Jira settings matches the one + your project needs to close an issue. -Make sure that the Jira issue is not already marked as resolved. That is, -the Jira issue resolution field is not set, and the issue is not struck through in -Jira lists. +- Make sure the Jira issue is not already marked as resolved: + - Check the Jira issue resolution field is not set. + - Check the issue is not struck through in Jira lists. ### CAPTCHA @@ -104,8 +111,3 @@ authenticate with the Jira site. To fix this error, sign in to your Jira instance and complete the CAPTCHA. - -## Third-party Jira integrations - -Developers have built several third-party Jira integrations for GitLab that are -listed on the [Atlassian Marketplace](https://marketplace.atlassian.com/search?product=jira&query=gitlab). diff --git a/doc/integration/jira/jira_cloud_configuration.md b/doc/integration/jira/jira_cloud_configuration.md index 0cfffdb8ba4..08cd34860ff 100644 --- a/doc/integration/jira/jira_cloud_configuration.md +++ b/doc/integration/jira/jira_cloud_configuration.md @@ -4,18 +4,19 @@ 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 --- -# Create an API token in Jira on Atlassian cloud **(FREE)** +# Create an API token for Jira in Atlassian cloud **(FREE)** You need an API token to [integrate with Jira](index.md) 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 > Atlassian account settings > Security > Create and manage API tokens**. -1. Select **Create API token** to display a modal window with an API token. +1. Sign in to [Atlassian](https://id.atlassian.com/manage-profile/security/api-tokens) + using an account with *write* access to Jira projects. + + The link opens the API tokens page. Alternatively, to go to this page from your Atlassian + profile, select **Account Settings > Security > Create and manage API tokens**. +1. Select **Create API token**. 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). +1. To copy the API token, select **Copy**, then paste the token somewhere safe. You need the newly created token, and the email address you used when you created it, when you diff --git a/doc/integration/jira/jira_server_configuration.md b/doc/integration/jira/jira_server_configuration.md index 32a8cd430f9..63625dd5065 100644 --- a/doc/integration/jira/jira_server_configuration.md +++ b/doc/integration/jira/jira_server_configuration.md @@ -17,9 +17,9 @@ credentials, you must: ## Create a Jira Server user -This process creates a user named `gitlab` and adds it to a new group named `gitlab-developers`: +This process creates a user named `gitlab`: -1. Sign in to your Jira instance as an administrator. +1. Sign in to your Jira instance as a Jira administrator. 1. In the upper right corner of the top menu, go to the gear icon and select **User Management**. 1. Create a new user account (`gitlab`) with write access to @@ -37,13 +37,15 @@ After you create the user, create a group for it. ## Create a Jira Server group -After you [create a Jira Server user](#create-a-jira-server-user), you can create a -group to assign permissions to the user: +After you [create a Jira Server user](#create-a-jira-server-user), create a +group to assign permissions to the user. -1. Sign in to your Jira instance as an administrator. +This process adds the `gitlab` user you created to a new group named `gitlab-developers`: + +1. Sign in to your Jira instance as a Jira administrator. 1. In the upper right corner of the top menu, go to the gear icon and select **User Management**. -1. From the sidebar, select **Groups**. +1. On the sidebar, select **Groups**.  @@ -52,12 +54,12 @@ group to assign permissions to the user: 1. To add the `gitlab` user to the `gitlab-developers` group, select **Edit members**. The `gitlab-developers` group should be listed in the leftmost box as a selected group. -1. In the **Add members to selected group(s)** area, enter `gitlab`. +1. In the **Add members to selected group(s)** section, enter `gitlab`. 1. Select **Add selected users**. -Jira saves your selection, and `gitlab` should appear in the **Group member(s)** -area. + The `gitlab` user appears in the **Group member(s)** + section. - +  Next, create a permission scheme for your group. @@ -65,16 +67,16 @@ Next, create a permission scheme for your group. After creating the group in Jira, grant permissions to the group by creating a permission scheme: -1. Sign in to your Jira instance as an administrator. +1. Sign in to your Jira instance as a Jira administrator. 1. In the upper right corner of the top menu, go to the gear icon and select **Issues**. -1. From the sidebar, select **Permission Schemes**. +1. On the sidebar, select **Permission Schemes**. 1. Select **Add Permission Scheme**, enter a **Name** and (optionally) a **Description**, and then select **Add**. 1. In the permissions scheme list, locate your new permissions scheme, and select **Permissions**. -1. Next to **Administer Projects**, select **Edit**. In - the **Group** list, select `gitlab-developers`. +1. Next to **Administer Projects**, select **Edit**. +1. From the **Group** dropdown list, select `gitlab-developers`, and then select **Grant**.  |