From 918bd1e7415785e7801468f0efc6104696cbbca9 Mon Sep 17 00:00:00 2001 From: Felipe Artur Date: Wed, 17 Oct 2018 10:46:06 +0000 Subject: Allow JIRA to login using email and API token --- .../project/integrations/img/jira_api_token.png | Bin 0 -> 160587 bytes .../integrations/img/jira_api_token_menu.png | Bin 0 -> 68564 bytes .../project/integrations/img/jira_service_page.png | Bin 47533 -> 74893 bytes doc/user/project/integrations/jira.md | 57 +++------------------ .../integrations/jira_cloud_configuration.md | 19 +++++++ .../integrations/jira_server_configuration.md | 53 +++++++++++++++++++ 6 files changed, 78 insertions(+), 51 deletions(-) create mode 100644 doc/user/project/integrations/img/jira_api_token.png create mode 100644 doc/user/project/integrations/img/jira_api_token_menu.png create mode 100644 doc/user/project/integrations/jira_cloud_configuration.md create mode 100644 doc/user/project/integrations/jira_server_configuration.md (limited to 'doc') diff --git a/doc/user/project/integrations/img/jira_api_token.png b/doc/user/project/integrations/img/jira_api_token.png new file mode 100644 index 00000000000..2c64f7bc44f Binary files /dev/null and b/doc/user/project/integrations/img/jira_api_token.png differ diff --git a/doc/user/project/integrations/img/jira_api_token_menu.png b/doc/user/project/integrations/img/jira_api_token_menu.png new file mode 100644 index 00000000000..20655ba3c0e Binary files /dev/null and b/doc/user/project/integrations/img/jira_api_token_menu.png differ diff --git a/doc/user/project/integrations/img/jira_service_page.png b/doc/user/project/integrations/img/jira_service_page.png index c75c11888a8..869d562ed5b 100644 Binary files a/doc/user/project/integrations/img/jira_service_page.png and b/doc/user/project/integrations/img/jira_service_page.png differ diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index 30f49fefc41..bc4bba40e59 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -45,56 +45,11 @@ project in Jira and then enter the correct values in GitLab. ### Configuring Jira -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. +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) -As an example, we'll create a user named `gitlab` and add it to the `Jira-developers` -group. - -**It is important that the user `gitlab` has 'write' access to projects in Jira** - -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** - go to **User Management** to create a new user. - - ![Jira user management link](img/jira_user_management_link.png) - -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._ - - ![Jira create new user](img/jira_create_new_user.png) - -1. Now, let's create a `gitlab-developers` group which will have write access - to projects in Jira. Go to the **Groups** tab and select **Create group**. - - ![Jira create new user](img/jira_create_new_group.png) - - Give it an optional description and click **Create group**. - - ![Jira create new group](img/jira_create_new_group_name.png) - -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 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. +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) ### Configuring GitLab @@ -117,8 +72,8 @@ in the table below. | ----- | ----------- | | `Web URL` | The base URL to the Jira instance web interface which is being linked to this GitLab project. E.g., `https://Jira.example.com`. | | `Jira API URL` | The base URL to the Jira instance API. Web URL value will be used if not set. E.g., `https://jira-api.example.com`. | -| `Username` | The user name created in [configuring Jira step](#configuring-jira). Using the email address will cause `401 unauthorized`. | -| `Password` |The password of the user created in [configuring Jira step](#configuring-jira). | +| `Username/Email` | Created when [configuring Jira step](#configuring-jira). Use `username` for **JIRA server** or `email` for **JIRA cloud**. | +| `Password/API token` |Created in [configuring Jira step](#configuring-jira). Use `password` for **JIRA server** or `API token` for **JIRA cloud**. | | `Transition ID` | This is the ID of a transition that moves issues to the desired state. It is possible to insert transition ids separated by `,` or `;` which means the issue will be moved to each state after another using the given order. **Closing Jira issues via commits or Merge Requests won't work if you don't set the ID correctly.** | ### Obtaining a transition ID diff --git a/doc/user/project/integrations/jira_cloud_configuration.md b/doc/user/project/integrations/jira_cloud_configuration.md new file mode 100644 index 00000000000..2e6e8278e64 --- /dev/null +++ b/doc/user/project/integrations/jira_cloud_configuration.md @@ -0,0 +1,19 @@ +# Creating an API token in JIRA cloud + +An API token is needed when integrating with JIRA Cloud, follow the steps +below to create one: + +1. Log in to https://id.atlassian.com with your email. +2. **Click API tokens**, then **Create API token**. + +![JIRA API token](img/jira_api_token_menu.png) + +![JIRA API token](img/jira_api_token.png) + +3. Make sure to write down your new API token as you will need it in the next [steps](jira.md#configuring-gitlab). + +NOTE: **Note** +It is important that the user associated with this email has 'write' access to projects in JIRA. + +The JIRA configuration is complete. You are going to need this new created token and the email you used to log in when [configuring GitLab in the next section](jira.md#configuring-gitlab). + diff --git a/doc/user/project/integrations/jira_server_configuration.md b/doc/user/project/integrations/jira_server_configuration.md new file mode 100644 index 00000000000..7d84ad0b07c --- /dev/null +++ b/doc/user/project/integrations/jira_server_configuration.md @@ -0,0 +1,53 @@ +# 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. + +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. + +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** + go to **User Management** to create a new user. + + ![Jira user management link](img/jira_user_management_link.png) + +2. 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._ + + ![Jira create new user](img/jira_create_new_user.png) + +3. Create a `gitlab-developers` group which will have write access + to projects in Jira. Go to the **Groups** tab and select **Create group**. + + ![Jira create new user](img/jira_create_new_group.png) + + Give it an optional description and click **Create group**. + + ![Jira create new group](img/jira_create_new_group_name.png) + +4. To give the newly-created group 'write' access, go to + **Application access > View configuration** and add the `gitlab-developers` + group to Jira Core. + + ![Jira group access](img/jira_group_access.png) + +5. 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). -- cgit v1.2.3