Merge branch 'docs/58975-jira-integration-docs' into 'master'

Improve Jira Server documentation

Closes #58975

See merge request gitlab-org/gitlab-ce!28463

8 files changed, 27 insertions, 22 deletions

diff --git a/doc/user/project/integrations/img/jira_add_user_to_group.png b/doc/user/project/integrations/img/jira_add_user_to_group.png
index 27dac49260c..d8cf541a81e 100644
--- a/doc/user/project/integrations/img/jira_add_user_to_group.png
+++ b/doc/user/project/integrations/img/jira_add_user_to_group.png
diff --git a/doc/user/project/integrations/img/jira_added_user_to_group.png b/doc/user/project/integrations/img/jira_added_user_to_group.png
new file mode 100644
index 00000000000..b3e29a65d6e
--- /dev/null
+++ b/doc/user/project/integrations/img/jira_added_user_to_group.png
diff --git a/doc/user/project/integrations/img/jira_create_new_group.png b/doc/user/project/integrations/img/jira_create_new_group.png
index 06c4e84fc61..84be3a94a45 100644
--- a/doc/user/project/integrations/img/jira_create_new_group.png
+++ b/doc/user/project/integrations/img/jira_create_new_group.png
diff --git a/doc/user/project/integrations/img/jira_create_new_user.png b/doc/user/project/integrations/img/jira_create_new_user.png
index e9c03ed770d..8460dc98ef9 100644
--- a/doc/user/project/integrations/img/jira_create_new_user.png
+++ b/doc/user/project/integrations/img/jira_create_new_user.png
diff --git a/doc/user/project/integrations/img/jira_group_access.png b/doc/user/project/integrations/img/jira_group_access.png
index 448cc55504d..58cf114bd55 100644
--- a/doc/user/project/integrations/img/jira_group_access.png
+++ b/doc/user/project/integrations/img/jira_group_access.png
diff --git a/doc/user/project/integrations/img/jira_user_management_link.png b/doc/user/project/integrations/img/jira_user_management_link.png
index 5eb9d031c3e..43ef18da6c8 100644
--- a/doc/user/project/integrations/img/jira_user_management_link.png
+++ b/doc/user/project/integrations/img/jira_user_management_link.png
diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md
index a90167b9767..c652149052e 100644
--- a/doc/user/project/integrations/jira.md
+++ b/doc/user/project/integrations/jira.md
@@ -47,11 +47,11 @@ project in Jira and then enter the correct values in GitLab.
 
 When connecting to **JIRA Server**, which supports basic authentication, a **username and password** are required. Check the link below and proceed to the next step:
 
-- [Setting up an user in JIRA server](jira_server_configuration.md)
+- [Setting up a user in JIRA server](jira_server_configuration.md)
 
 When connecting to **JIRA Cloud**, which supports authentication via API token, an **email and API token**, are required. Check the link below and proceed to the next step:
 
-- [Setting up an user in JIRA cloud](jira_cloud_configuration.md)
+- [Setting up a user in JIRA cloud](jira_cloud_configuration.md)
 
 ### Configuring GitLab
 
diff --git a/doc/user/project/integrations/jira_server_configuration.md b/doc/user/project/integrations/jira_server_configuration.md
index 20036183187..13d65c4d8e4 100644
--- a/doc/user/project/integrations/jira_server_configuration.md
+++ b/doc/user/project/integrations/jira_server_configuration.md
@@ -1,18 +1,16 @@
 # 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. Login to your Jira instance as admin and under
-*Administration*, go to *User Management* and create a new user.
+need to integrate with GitLab.
 
 As an example, we'll create a user named `gitlab` and add it to the `Jira-developers`
 group.
 
 NOTE: **Note**
-It is important that the user `gitlab` has 'write' access to projects in Jira.
+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.
 
-We have split this stage in steps so it is easier to follow.
-
-1. Log in to your Jira instance as an administrator and under **Administration**
+1. Log in to your Jira instance as an administrator and under **Jira Administration**
    go to **User Management** to create a new user.
 
      ![Jira user management link](img/jira_user_management_link.png)
@@ -27,27 +25,34 @@ We have split this stage in steps so it is easier to follow.
 
      ![Jira create new user](img/jira_create_new_user.png)
 
-1. Create a `gitlab-developers` group which will have write access
-   to projects in Jira. Go to the **Groups** tab and select **Create group**.
+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**.
 
      ![Jira create new user](img/jira_create_new_group.png)
 
-     Give it an optional description and click **Create group**.
+     Give it a name and click **Add group**.
 
-     ![Jira create new group](img/jira_create_new_group_name.png)
+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. To give the newly-created group 'write' access, go to
-   **Application access > View configuration** and add the `gitlab-developers`
-   group to Jira Core.
+     ![Jira add user to group](img/jira_add_user_to_group.png)
+     
+   Click **Add selected users** and `gitlab` should appear in the **Group member(s)** box.
+   This membership is saved automatically.
+   
+     ![Jira added user to group](img/jira_added_user_to_group.png)
+
+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. 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.
 
      ![Jira group access](img/jira_group_access.png)
 
-1. Add the `gitlab` user to the `gitlab-developers` group by going to
-   **Users > GitLab user > Add group** and selecting the `gitlab-developers`
-   group from the dropdown menu. Notice that the group says _Access_, which is
-   intended as part of this process.
-
-     ![Jira add user to group](img/jira_add_user_to_group.png)
-
 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).