From d4425e566481ef002f746ab266b1cbb2332f3c25 Mon Sep 17 00:00:00 2001 From: Russell Dickenson Date: Tue, 30 Jul 2019 13:59:53 +1000 Subject: Simplified Jira integration instructions Jira Cloud instructions - Corrected numbering of steps. - Moved each screenshot next to the relevant step. - Rewrote the conclusion to more clearly direct the reader to the next procedure. Jira Server instructions - Removed all screenshots. - Expanded what were single steps into multiple steps, to make the procedure easier to follow. - Added an introduction, detailing what the procedure would accomplish. - Edited references to the UI elements to avoid references to screen positioning. - Rewrote the conclusion to more clearly direct the reader to the next procedure. --- .../integrations/jira_cloud_configuration.md | 12 +-- .../integrations/jira_server_configuration.md | 85 ++++++++++++---------- 2 files changed, 53 insertions(+), 44 deletions(-) diff --git a/doc/user/project/integrations/jira_cloud_configuration.md b/doc/user/project/integrations/jira_cloud_configuration.md index 5a5ba2dd168..9c755742c05 100644 --- a/doc/user/project/integrations/jira_cloud_configuration.md +++ b/doc/user/project/integrations/jira_cloud_configuration.md @@ -9,12 +9,14 @@ below to create one: It is important that the user associated with this email address has *write* access to projects in Jira. -2. Click **Create API token**. +1. Click **Create API token**. -![Jira API token](img/jira_api_token_menu.png) + ![Create Jira API token](img/jira_api_token_menu.png) -![Jira API token](img/jira_api_token.png) +1. Click **Copy to clipboard**, or click **View** and write down the new API token. -1. Click **Copy to clipboard**, or click **View** and write down the new API token. It is required when [configuring GitLab](jira.md#configuring-gitlab). + ![View Jira API token](img/jira_api_token.png) -The Jira configuration is complete. You need the newly created token, and the associated email address, when [configuring GitLab](jira.md#configuring-gitlab) in the next section. +The Jira configuration is complete. You need the newly created API token, and the associated email address to complete the integration of GitLab and Jira. + +Continue to [configuring GitLab](jira.md#configuring-gitlab). diff --git a/doc/user/project/integrations/jira_server_configuration.md b/doc/user/project/integrations/jira_server_configuration.md index 5116cbfe9ac..fe9f4e0fb88 100644 --- a/doc/user/project/integrations/jira_server_configuration.md +++ b/doc/user/project/integrations/jira_server_configuration.md @@ -1,58 +1,65 @@ # Creating a username and password for Jira Server -We need to create a user in Jira which will have access to all projects that -need to integrate with GitLab. +To allow GitLab access to Jira projects, you need to: -As an example, we'll create a user named `gitlab` and add it to the `Jira-developers` -group. +- Create a Jira user to be used by GitLab: `gitlab`. +- Create a Jira group, to which you will grant access to Jira projects: `gitlab-developers`. +- Assign the new user to the new group. +- Grant permissions to the new group. -NOTE: **Note** -It is important that the Jira user created for the integration is given 'write' -access to your Jira projects. This is covered in the process below. +1. Log in to your Jira instance as an administrator. -1. Log in to your Jira instance as an administrator and under **Jira Administration** - go to **User Management** to create a new user. +1. Go to **Jira Administration > User Management**. - ![Jira user management link](img/jira_user_management_link.png) +1. Click **Users** in the sidebar. -1. The next step is to create a new user (e.g., `gitlab`) who has write access - to projects in Jira. Enter the user's name and a _valid_ e-mail address - since Jira sends a verification e-mail to set up the password. - _**Note:** Jira creates the username automatically by using the e-mail - prefix. You can change it later, if needed. Our integration does not support SSO (such as SAML). You will need to create - an HTTP basic authentication password. You can do this by visiting the user - profile, looking up the username, and setting a password._ +1. Click **Create**. + - Complete the following fields: + - Email address + - Full name + - Username + - Password + - Select the **Jira Software** checkbox. + - Click **Create user**. - ![Jira create new user](img/jira_create_new_user.png) +1. Go to **Jira Administration > User Management**. -1. Create a `gitlab-developers` group. (We will give this group write access to Jira - projects in a later step). Go to the **Groups** tab on the left, and select **Add group**. +1. Click **Groups** in the sidebar. - ![Jira create new user](img/jira_create_new_group.png) +1. Enter `gitlab-developers` in the **Name** field, and click **Add group**. - Give it a name and click **Add group**. +1. Click **Edit members** in the **gitlab-developers** row. -1. Add the `gitlab` user to the `gitlab-developers` group by clicking **Edit members**. - The `gitlab-developers` group should be listed in the leftmost box as a selected group. - Under **Add members to selected group(s)**, enter `gitlab`. +1. Enter the username of the newly-created user in **Add members to selected group(s)**. - ![Jira add user to group](img/jira_add_user_to_group.png) +1. Click **Add selected users**. - Click **Add selected users** and `gitlab` should appear in the **Group member(s)** box. - This membership is saved automatically. + The `gitlab-developers` group should now appear in **Group member(s)**. - ![Jira added user to group](img/jira_added_user_to_group.png) +1. Click the cog icon, and select **Issues**. -1. To give the newly-created group 'write' access, you need to create a **Permission Scheme**. - To do this, click the gear icon and select **Issues**. Then click **Permission Schemes**. - Click **Add Permission Scheme** and enter a **Name** and, optionally, a **Description**. +1. Click **Permission Schemes**. -1. Once your permission scheme is created, you'll be taken back to the permissions scheme list. - Locate your new permissions scheme and click **Permissions**. Next to **Administer Projects**, - click **Edit**. In the resulting dialog box, select **Group** and select `gitlab-developers` - from the dropdown. +1. Click **Add Permission Scheme**. - ![Jira group access](img/jira_group_access.png) +1. In the **Add Permission Scheme** form, enter a **Name**, and a brief **Description**. -The Jira configuration is complete. Write down the new Jira username and its -password as they will be needed when [configuring GitLab in the next section](jira.md#configuring-gitlab). +1. Click **Add**. + + You'll then be at the **Permission Schemes** page. + +1. Locate the new permissions scheme, and click **Permissions** in the **Actions** column. + +1. Click **Edit** beside the **Administer Projects** permission. + + You'll then see the **Grant permission** dialog. + +1. Click **Group**. + +1. Select **gitlab-developers** from the **Group** dropdown. + +1. Click **Grant**. + +The Jira configuration is complete. You need the new Jira username and password to complete the integration of GitLab and Jira. + +Continue to [configuring GitLab](jira.md#configuring-gitlab). -- cgit v1.2.1