Skip to content

Commit 2d33579

Browse files
VirtuaCreativeVirtuaCreative
committed
Merge branch 'docs-jira-update' into 'master'
Port Jira integration documentation update to CE Closes #50505 See merge request gitlab-org/gitlab-ce!22062
2 parents fb438b9 + 7848e42 commit 2d33579

File tree

1 file changed

+119
-117
lines changed
  • doc/user/project/integrations

1 file changed

+119
-117
lines changed

‎doc/user/project/integrations/jira.md

Lines changed: 119 additions & 117 deletions
Original file line numberDiff line numberDiff line change
@@ -1,123 +1,129 @@
1-
# GitLab JIRA integration
1+
# GitLab Jira integration
22

3-
GitLab can be configured to interact with [JIRA], a project management platform.
3+
GitLab Issues are a powerful tool for discussing ideas and planning and tracking work.
4+
However, many organizations have been using Jira for these purposes and have
5+
extensive data and business processes built into it.
46

5-
Once your GitLab project is connected to JIRA, you can reference and close the
6-
issues in JIRA directly from GitLab.
7+
While you can always migrate content and process from Jira to GitLab Issues,
8+
you can also opt to continue using Jira and use it together with GitLab through
9+
our integration.
710

8-
For a use case, check out this article of [How and why to integrate GitLab with
9-
JIRA](https://www.programmableweb.com/news/how-and-why-to-integrate-gitlab-jira/how-to/2017/04/25).
11+
Once you integrate your GitLab project with your Jira instance, you can automatically
12+
detect and cross-reference activity between the GitLab project and any of your projects
13+
in Jira. This includes the ability to close or transition Jira issues when the work
14+
is completed in GitLab.
15+
16+
Here's how the integration responds when you take the following actions in GitLab:
17+
18+
- **Mention a Jira issue ID** in a commit message or MR (merge request).
19+
- GitLab hyperlinks to the Jira issue.
20+
- The Jira issue adds an issue link to the commit/MR in GitLab.
21+
- The Jira issue adds a comment reflecting the comment made in GitLab, the comment author, and a link to the commit/MR in GitLab.
22+
- **Mention that a commit or MR 'closes', 'resolves', or 'fixes' a Jira issue ID**. When the commit is made on master or the change is merged to master:
23+
- GitLab's merge request page displays a note that it "Closed" the Jira issue, with a link to the issue. (Note: Before the merge, an MR will display that it "Closes" the Jira issue.)
24+
- The Jira issue shows the activity and the Jira issue is closed, or otherwise transitioned.
25+
26+
You can also use [Jira's Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-298976812.html)
27+
directly from GitLab, as covered in the article
28+
[How and why to integrate GitLab with Jira](https://www.programmableweb.com/news/how-and-why-to-integrate-gitlab-Jira/how-to/2017/04/25).
1029

1130
## Configuration
1231

13-
Each GitLab project can be configured to connect to a different JIRA instance. That
14-
means one GitLab project maps to _all_ JIRA projects in that JIRA instance once
15-
the configuration is set up. Therefore, you don't have to explicitly associate
16-
one GitLab project to any JIRA project. Once the configuration is set up, any JIRA
17-
projects in the JIRA instance are already mapped to the GitLab project.
32+
Each GitLab project can be configured to connect to an entire Jira instance. That
33+
means one GitLab project can interact with _all_ Jira projects in that instance, once
34+
configured. Therefore, you will not have to explicitly associate
35+
a GitLab project with any single Jira project.
1836

19-
If you have one JIRA instance you can pre-fill the settings page with a default
20-
template, see the [Services Templates][services-templates] docs.
37+
If you have one Jira instance, you can pre-fill the settings page with a default
38+
template. See the [Services Templates][services-templates] docs.
2139

22-
Configuration happens via user name and password. Connecting to a JIRA server
40+
Configuration happens via user name and password. Connecting to a Jira server
2341
via CAS is not possible.
2442

25-
In order to enable the JIRA service in GitLab, you need to first configure the
26-
project in JIRA and then enter the correct values in GitLab.
43+
In order to enable the Jira service in GitLab, you need to first configure the
44+
project in Jira and then enter the correct values in GitLab.
2745

28-
### Configuring JIRA
46+
### Configuring Jira
2947

30-
We need to create a user in JIRA which will have access to all projects that
31-
need to integrate with GitLab. Login to your JIRA instance as admin and under
32-
Administration go to User Management and create a new user.
48+
We need to create a user in Jira which will have access to all projects that
49+
need to integrate with GitLab. Login to your Jira instance as admin and under
50+
*Administration*, go to *User Management* and create a new user.
3351

34-
As an example, we'll create a user named `gitlab` and add it to `JIRA-developers`
52+
As an example, we'll create a user named `gitlab` and add it to the `Jira-developers`
3553
group.
3654

37-
**It is important that the user `GitLab` has write-access to projects in JIRA**
55+
**It is important that the user `gitlab` has 'write' access to projects in Jira**
3856

3957
We have split this stage in steps so it is easier to follow.
4058

41-
---
42-
43-
1. Login to your JIRA instance as an administrator and under **Administration**
59+
1. Log in to your Jira instance as an administrator and under **Administration**
4460
go to **User Management** to create a new user.
4561

46-
![JIRA user management link](img/jira_user_management_link.png)
47-
48-
---
62+
![Jira user management link](img/jira_user_management_link.png)
4963

5064
1. The next step is to create a new user (e.g., `gitlab`) who has write access
51-
to projects in JIRA. Enter the user's name and a _valid_ e-mail address
52-
since JIRA sends a verification e-mail to set up the password.
53-
_**Note:** JIRA creates the username automatically by using the e-mail
54-
prefix. You can change it later if you want._
65+
to projects in Jira. Enter the user's name and a _valid_ e-mail address
66+
since Jira sends a verification e-mail to set up the password.
67+
_**Note:** Jira creates the username automatically by using the e-mail
68+
prefix. You can change it later, if needed. Our integration does not support SSO (such as SAML). You will need to create
69+
an HTTP basic authentication password. You can do this by visiting the user
70+
profile, looking up the username, and setting a password._
5571

56-
![JIRA create new user](img/jira_create_new_user.png)
57-
58-
---
72+
![Jira create new user](img/jira_create_new_user.png)
5973

6074
1. Now, let's create a `gitlab-developers` group which will have write access
61-
to projects in JIRA. Go to the **Groups** tab and select **Create group**.
62-
63-
![JIRA create new user](img/jira_create_new_group.png)
64-
65-
---
66-
67-
Give it an optional description and hit **Create group**.
75+
to projects in Jira. Go to the **Groups** tab and select **Create group**.
6876

69-
![jira create new group](img/jira_create_new_group_name.png)
77+
![Jira create new user](img/jira_create_new_group.png)
7078

71-
---
79+
Give it an optional description and click **Create group**.
7280

73-
1. Give the newly-created group write access by going to
74-
**Application access ➔ View configuration** and adding the `gitlab-developers`
75-
group to JIRA Core.
81+
![Jira create new group](img/jira_create_new_group_name.png)
7682

77-
![JIRA group access](img/jira_group_access.png)
83+
1. To give the newly-created group 'write' access, go to
84+
**Application access ➔ View configuration** and add the `gitlab-developers`
85+
group to Jira Core.
7886

79-
---
87+
![Jira group access](img/jira_group_access.png)
8088

8189
1. Add the `gitlab` user to the `gitlab-developers` group by going to
8290
**Users ➔ GitLab user ➔ Add group** and selecting the `gitlab-developers`
83-
group from the dropdown menu. Notice that the group says _Access_ which is
84-
what we aim for.
91+
group from the dropdown menu. Notice that the group says _Access_, which is
92+
intended as part of this process.
8593

86-
![JIRA add user to group](img/jira_add_user_to_group.png)
94+
![Jira add user to group](img/jira_add_user_to_group.png)
8795

88-
---
89-
90-
The JIRA configuration is over. Write down the new JIRA username and its
96+
The Jira configuration is complete. Write down the new Jira username and its
9197
password as they will be needed when configuring GitLab in the next section.
9298

9399
### Configuring GitLab
94100

95101
> **Notes:**
96-
> - The currently supported JIRA versions are `v6.x` and `v7.x.`. GitLab 7.8 or
102+
> - The currently supported Jira versions are `v6.x` and `v7.x.`. GitLab 7.8 or
97103
> higher is required.
98-
> - GitLab 8.14 introduced a new way to integrate with JIRA which greatly simplified
104+
> - GitLab 8.14 introduced a new way to integrate with Jira which greatly simplified
99105
> the configuration options you have to enter. If you are using an older version,
100106
> [follow this documentation][jira-repo-old-docs].
101107
> - In order to support Oracle's Access Manager, GitLab will send additional cookies
102108
> to enable Basic Auth. The cookie being added to each request is `OBBasicAuth` with
103109
> a value of `fromDialog`.
104110
105-
To enable JIRA integration in a project, navigate to the
111+
To enable Jira integration in a project, navigate to the
106112
[Integrations page](project_services.md#accessing-the-project-services), click
107-
the **JIRA** service, and fill in the required details on the page as described
113+
the **Jira** service, and fill in the required details on the page as described
108114
in the table below.
109115

110116
| Field | Description |
111117
| ----- | ----------- |
112-
| `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`. |
113-
| `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`. |
114-
| `Username` | The user name created in [configuring JIRA step](#configuring-jira). Using the email address will cause `401 unauthorized`. |
115-
| `Password` |The password of the user created in [configuring JIRA step](#configuring-jira). |
116-
| `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.** |
118+
| `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`. |
119+
| `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`. |
120+
| `Username` | The user name created in [configuring Jira step](#configuring-jira). Using the email address will cause `401 unauthorized`. |
121+
| `Password` |The password of the user created in [configuring Jira step](#configuring-jira). |
122+
| `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.** |
117123

118-
### Getting a transition ID
124+
### Obtaining a transition ID
119125

120-
In the most recent JIRA UI, you can no longer see transition IDs in the workflow
126+
In the most recent Jira user interface, you can no longer see transition IDs in the workflow
121127
administration UI. You can get the ID you need in either of the following ways:
122128

123129
1. By using the API, with a request like `https://yourcompany.atlassian.net/rest/api/2/issue/ISSUE-123/transitions`
@@ -129,25 +135,23 @@ Note that the transition ID may vary between workflows (e.g., bug vs. story),
129135
even if the status you are changing to is the same.
130136

131137
After saving the configuration, your GitLab project will be able to interact
132-
with all JIRA projects in your JIRA instance and you'll see the JIRA link on the GitLab project pages that takes you to the appropriate JIRA project.
133-
134-
![JIRA service page](img/jira_service_page.png)
138+
with all Jira projects in your Jira instance and you'll see the Jira link on the GitLab project pages that takes you to the appropriate Jira project.
135139

136-
---
140+
![Jira service page](img/jira_service_page.png)
137141

138-
## JIRA issues
142+
## Jira issues
139143

140-
By now you should have [configured JIRA](#configuring-jira) and enabled the
141-
[JIRA service in GitLab](#configuring-gitlab). If everything is set up correctly
142-
you should be able to reference and close JIRA issues by just mentioning their
144+
By now you should have [configured Jira](#configuring-jira) and enabled the
145+
[Jira service in GitLab](#configuring-gitlab). If everything is set up correctly
146+
you should be able to reference and close Jira issues by just mentioning their
143147
ID in GitLab commits and merge requests.
144148

145-
### Referencing JIRA Issues
149+
### Referencing Jira Issues
146150

147-
When GitLab project has JIRA issue tracker configured and enabled, mentioning
148-
JIRA issue in GitLab will automatically add a comment in JIRA issue with the
151+
When GitLab project has Jira issue tracker configured and enabled, mentioning
152+
Jira issue in GitLab will automatically add a comment in Jira issue with the
149153
link back to GitLab. This means that in comments in merge requests and commits
150-
referencing an issue, e.g., `PROJECT-7`, will add a comment in JIRA issue in the
154+
referencing an issue, e.g., `PROJECT-7`, will add a comment in Jira issue in the
151155
format:
152156

153157
```
@@ -156,21 +160,19 @@ ENTITY_TITLE
156160
```
157161

158162
* `USER` A user that mentioned the issue. This is the link to the user profile in GitLab.
159-
* `LINK_TO_THE_COMMENT` Link to the origin of mention with a name of the entity where JIRA issue was mentioned.
163+
* `LINK_TO_THE_COMMENT` Link to the origin of mention with a name of the entity where Jira issue was mentioned.
160164
* `RESOURCE_NAME` Kind of resource which referenced the issue. Can be a commit or merge request.
161165
* `PROJECT_NAME` GitLab project name.
162166
* `ENTITY_TITLE` Merge request title or commit message first line.
163167

164-
![example of mentioning or closing the JIRA issue](img/jira_issue_reference.png)
168+
![example of mentioning or closing the Jira issue](img/jira_issue_reference.png)
165169

166-
---
170+
### Closing Jira Issues
167171

168-
### Closing JIRA Issues
169-
170-
JIRA issues can be closed directly from GitLab by using trigger words in
172+
Jira issues can be closed directly from GitLab by using trigger words in
171173
commits and merge requests. When a commit which contains the trigger word
172-
followed by the JIRA issue ID in the commit message is pushed, GitLab will
173-
add a comment in the mentioned JIRA issue and immediately close it (provided
174+
followed by the Jira issue ID in the commit message is pushed, GitLab will
175+
add a comment in the mentioned Jira issue and immediately close it (provided
174176
the transition ID was set up correctly).
175177

176178
There are currently three trigger words, and you can use either one to achieve
@@ -180,66 +182,66 @@ the same goal:
180182
- `Closes PROJECT-1`
181183
- `Fixes PROJECT-1`
182184

183-
where `PROJECT-1` is the issue ID of the JIRA project.
185+
where `PROJECT-1` is the issue ID of the Jira project.
184186

185187
> **Notes:**
186188
> - Only commits and merges into the project's default branch (usually **master**) will
187189
> close an issue in Jira. You can change your projects default branch under
188190
> [project settings](img/jira_project_settings.png).
189-
> - The JIRA issue will not be transitioned if it has a resolution.
191+
> - The Jira issue will not be transitioned if it has a resolution.
190192
191-
### JIRA issue closing example
193+
### Jira issue closing example
192194

193195
Let's consider the following example:
194196

195-
1. For the project named `PROJECT` in JIRA, we implemented a new feature
197+
1. For the project named `PROJECT` in Jira, we implemented a new feature
196198
and created a merge request in GitLab.
197-
1. This feature was requested in JIRA issue `PROJECT-7` and the merge request
199+
1. This feature was requested in Jira issue `PROJECT-7` and the merge request
198200
in GitLab contains the improvement
199201
1. In the merge request description we use the issue closing trigger
200202
`Closes PROJECT-7`.
201-
1. Once the merge request is merged, the JIRA issue will be automatically closed
203+
1. Once the merge request is merged, the Jira issue will be automatically closed
202204
with a comment and an associated link to the commit that resolved the issue.
203205

204-
---
205-
206-
In the following screenshot you can see what the link references to the JIRA
206+
In the following screenshot you can see what the link references to the Jira
207207
issue look like.
208208

209-
![A Git commit that causes the JIRA issue to be closed](img/jira_merge_request_close.png)
209+
![A Git commit that causes the Jira issue to be closed](img/jira_merge_request_close.png)
210210

211-
---
212-
213-
Once this merge request is merged, the JIRA issue will be automatically closed
211+
Once this merge request is merged, the Jira issue will be automatically closed
214212
with a link to the commit that resolved the issue.
215213

216-
![The GitLab integration closes JIRA issue](img/jira_service_close_issue.png)
217-
218-
---
214+
![The GitLab integration closes Jira issue](img/jira_service_close_issue.png)
219215

220-
![The GitLab integration creates a comment and a link on JIRA issue.](img/jira_service_close_comment.png)
216+
![The GitLab integration creates a comment and a link on Jira issue.](img/jira_service_close_comment.png)
221217

222218
## Troubleshooting
223219

224-
If things don't work as expected that's usually because you have configured
225-
incorrectly the JIRA-GitLab integration.
220+
If these features do not work as expected, it is likely due to a problem with the way the integration settings were configured.
221+
222+
### GitLab is unable to comment on a Jira issue
223+
224+
Make sure that the Jira user you set up for the integration has the
225+
correct access permission to post comments on a Jira issue and also to transition
226+
the issue, if you'd like GitLab to also be able to do so.
227+
Jira issue references and update comments will not work if the GitLab issue tracker is disabled.
226228

227-
### GitLab is unable to comment on a ticket
229+
### GitLab is unable to close a Jira issue
228230

229-
Make sure that the user you set up for GitLab to communicate with JIRA has the
230-
correct access permission to post comments on a ticket and to also transition
231-
the ticket, if you'd like GitLab to also take care of closing them.
232-
JIRA issue references and update comments will not work if the GitLab issue tracker is disabled.
231+
Make sure the `Transition ID` you set within the Jira settings matches the one
232+
your project needs to close an issue.
233233

234-
### GitLab is unable to close a ticket
234+
Make sure that the Jira issue is not already marked as resolved; that is,
235+
the Jira issue resolution field is not set. (It should not be struck through in
236+
Jira lists.)
235237

236-
Make sure the `Transition ID` you set within the JIRA settings matches the one
237-
your project needs to close a ticket.
238+
### CAPTCHA
238239

239-
Make sure that the JIRA issue is not already marked as resolved, in other words that
240-
the JIRA issue resolution field is not set. (It should not be struck through in
241-
JIRA lists.)
240+
CAPTCHA may be triggered after several consecutive failed login attempts
241+
which may lead to a `401 unauthorized` error when testing your Jira integration.
242+
If CAPTCHA has been triggered, you will not be able to use Jira's REST API to
243+
authenticate with the Jira site. You will need to log in to your Jira instance
244+
and complete the CAPTCHA.
242245

243246
[services-templates]: services_templates.md
244247
[jira-repo-old-docs]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-13-stable/doc/project_services/jira.md
245-
[jira]: https://www.atlassian.com/software/jira

0 commit comments

Comments
 (0)