diff options
Diffstat (limited to 'doc/integration/jira/issues.md')
| -rw-r--r-- | doc/integration/jira/issues.md | 238 |
1 files changed, 135 insertions, 103 deletions
diff --git a/doc/integration/jira/issues.md b/doc/integration/jira/issues.md index d2cab59742b..91311f85310 100644 --- a/doc/integration/jira/issues.md +++ b/doc/integration/jira/issues.md @@ -6,168 +6,200 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Jira integration issue management **(FREE)** -By now you should have [configured Jira](development_panel.md#configuration) and enabled the -[Jira service in GitLab](development_panel.md#configure-gitlab). If everything is set up correctly -you should be able to reference and close Jira issues by just mentioning their -ID in GitLab commits and merge requests. +Integrating issue management with Jira requires you to [configure Jira](development_panel.md#configure-the-integration) +and [enable the Jira service](development_panel.md#configure-gitlab) in GitLab. +After you configure and enable the integration, you can reference and close Jira +issues by mentioning the Jira ID in GitLab commits and merge requests. -Jira issue IDs must be formatted in uppercase for the integration to work. +The Jira integration requires to you format any Jira issue IDs in uppercase. ## Reference Jira issues -When GitLab project has Jira issue tracker configured and enabled, mentioning -Jira issues in GitLab automatically adds a comment in Jira issue with the -link back to GitLab. This means that in comments in merge requests and commits -referencing an issue, `PROJECT-7` for example, adds a comment in Jira issue in the -format: +With this integration, you can cross-reference Jira issues while you work in +GitLab issues and merge requests. Mention a Jira issue in a GitLab issue, +merge request, or comment, and GitLab adds a formatted comment to the Jira issue. +The comment links back to your work in GitLab. -```plaintext -USER mentioned this issue in RESOURCE_NAME of [PROJECT_NAME|LINK_TO_COMMENT]: -ENTITY_TITLE +For example, this commit references the Jira issue `GIT-1`: + +```shell +git commit -m "GIT-1 this is a test commit" ``` -- `USER` A user that mentioned the issue. This is the link to the user profile in GitLab. -- `LINK_TO_THE_COMMENT` Link to the origin of mention with a name of the entity where Jira issue was mentioned. -- `RESOURCE_NAME` Kind of resource which referenced the issue. Can be a commit or merge request. -- `PROJECT_NAME` GitLab project name. -- `ENTITY_TITLE` Merge request title or commit message first line. +GitLab adds a reference to the **Issue Links** section of Jira issue `GIT-1`: - + -For example, the following commit references the Jira issue with `PROJECT-1` as its ID: +GitLab also adds a comment to the issue, and uses this format: -```shell -git commit -m "PROJECT-1 Fix spelling and grammar" +```plaintext +USER mentioned this issue in RESOURCE_NAME of [PROJECT_NAME|COMMENTLINK]: +ENTITY_TITLE ``` -## Close Jira issues +- `USER`: The name of the user who mentioned the issue, linked to their GitLab user profile. +- `COMMENTLINK`: A link to where the Jira issue was mentioned. +- `RESOURCE_NAME`: The type of resource, such as a commit or merge request, which referenced the issue. +- `PROJECT_NAME`: The GitLab project name. +- `ENTITY_TITLE`: The title of the merge request, or the first line of the commit. -Jira issues can be closed directly from GitLab by using trigger words in -commits and merge requests. When a commit which contains the trigger word -followed by the Jira issue ID in the commit message is pushed, GitLab -adds a comment in the mentioned Jira issue and immediately closes it (provided -the transition ID was set up correctly). +You can [disable comments](#disable-comments-on-jira-issues) on issues. -There are currently three trigger words, and you can use either one to achieve -the same goal: +### Require associated Jira issue for merge requests to be merged -- `Resolves PROJECT-1` -- `Closes PROJECT-1` -- `Fixes PROJECT-1` +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/280766) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.12 behind a feature flag, disabled by default. +> - [Deployed behind a feature flag](../../user/feature_flags.md), disabled by default. +> - Disabled on GitLab.com. +> - Not recommended for production use. +> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-the-ability-to-require-an-associated-jira-issue-on-merge-requests). **(ULTIMATE SELF)** -where `PROJECT-1` is the ID of the Jira issue. +This in-development feature might not be available for your use. There can be +[risks when enabling features still in development](../../user/application_security/index.md#security-approvals-in-merge-requests). +Refer to this feature's version history for more details. -Note the following: +You can prevent merge requests from being merged if they do not refer to a Jira issue. +To enforce this: -- Only commits and merges into the project's default branch (usually `master`) - close an issue in Jira. You can change your project's default branch under - [project settings](img/jira_project_settings.png). -- The Jira issue is not transitioned if it has a resolution. +1. Navigate to your project's **Settings > General** page. +1. Expand the **Merge requests** section. +1. Under **Merge checks**, select the **Require an associated issue from Jira** check box. +1. Select **Save** for the changes to take effect. -Let's consider the following example: +After you enable this feature, a merge request that doesn't reference an associated +Jira issue can't be merged. The merge request displays the message +**To merge, a Jira issue key must be mentioned in the title or description.** -1. For the project named `PROJECT` in Jira, we implemented a new feature - and created a merge request in GitLab. -1. This feature was requested in Jira issue `PROJECT-7` and the merge request - in GitLab contains the improvement -1. In the merge request description we use the issue closing trigger - `Closes PROJECT-7`. -1. Once the merge request is merged, the Jira issue is automatically closed - with a comment and an associated link to the commit that resolved the issue. +## Close Jira issues in GitLab -In the following screenshot you can see what the link references to the Jira -issue look like. +If you have configured GitLab transition IDs, you can close a Jira issue directly +from GitLab. Use a trigger word followed by a Jira issue ID in a commit or merge request. +When you push a commit containing a trigger word and Jira issue ID, GitLab: - +1. Comments in the mentioned Jira issue. +1. Closes the Jira issue. If the Jira issue has a resolution, it isn't transitioned. -Once this merge request is merged, the Jira issue is automatically closed -with a link to the commit that resolved the issue. +For example, use any of these trigger words to close the Jira issue `PROJECT-1`: - +- `Resolves PROJECT-1` +- `Closes PROJECT-1` +- `Fixes PROJECT-1` -## View Jira issues **(PREMIUM)** +The commit or merge request must target your project's [default branch](../../user/project/repository/branches/default.md). +You can change your project's default branch under [project settings](img/jira_project_settings.png). -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3622) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. +### Use case for closing issues -You can browse, search, and view issues from a selected Jira project directly in GitLab, -if your GitLab administrator [has configured it](development_panel.md#configure-gitlab): +Consider this example: -1. In the left navigation bar, go to **Jira > Issues list**. -1. The issue list sorts by **Created date** by default, with the newest issues listed at the top: +1. A user creates Jira issue `PROJECT-7` to request a new feature. +1. You create a merge request in GitLab to build the requested feature. +1. In the merge request, you add the issue closing trigger `Closes PROJECT-7`. +1. When the merge request is merged: + - GitLab closes the Jira issue for you: +  + - GitLab adds a formatted comment to Jira, linking back to the commit that + resolved the issue. You can [disable comments](#disable-comments-on-jira-issues). -  +## View Jira issues **(PREMIUM)** -1. To display the most recently updated issues first, click **Last updated**. -1. In GitLab versions 13.10 and later, you can view [individual Jira issues](#view-a-jira-issue). +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3622) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. -Issues are grouped into tabs based on their [Jira status](https://confluence.atlassian.com/adminjiraserver070/defining-status-field-values-749382903.html): +You can browse, search, and view issues from a selected Jira project directly in GitLab, +if your GitLab administrator [has configured it](development_panel.md#configure-gitlab). -- The **Open** tab displays all issues with a Jira status in any category other than Done. -- The **Closed** tab displays all issues with a Jira status categorized as Done. -- The **All** tab displays all issues of any status. +To do this, in GitLab, go to your project and select **Jira > Issues list**. The issue list +sorts by **Created date** by default, with the newest issues listed at the top: -## View a Jira issue + -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299832) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.10 behind a feature flag, disabled by default. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/299832) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.11. +- To display the most recently updated issues first, select **Last updated**. +- You can [search and filter](#search-and-filter-the-issues-list) the issues list. +- In GitLab [versions 13.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/299832), + you can select an issue from the list to view it in GitLab: +  -When viewing the [Jira issues list](#view-jira-issues), select an issue from the -list to open it in GitLab: +Issues are grouped into tabs based on their +[Jira status](https://confluence.atlassian.com/adminjiraserver070/defining-status-field-values-749382903.html): - +- **Open** tab: All issues with a Jira status in any category other than Done. +- **Closed** tab: All issues with a Jira status categorized as Done. +- **All** tab: All issues of any status. ## Search and filter the issues list To refine the list of issues, use the search bar to search for any text -contained in an issue summary (title) or description. - -You can also filter by labels, status, reporter, and assignee using URL parameters. -Enhancements to be able to use these through the user interface are [planned](https://gitlab.com/groups/gitlab-org/-/epics/3622). +contained in an issue summary (title) or description. Use any combination +of these filters: - To filter issues by `labels`, specify one or more labels as part of the `labels[]` -parameter in the URL. When using multiple labels, only issues that contain all specified -labels are listed. `/-/integrations/jira/issues?labels[]=backend&labels[]=feature&labels[]=QA` - -- To filter issues by `status`, specify the `status` parameter in the URL. -`/-/integrations/jira/issues?status=In Progress` - + parameter in the URL. When using multiple labels, only issues that contain all specified + labels are listed: `/-/integrations/jira/issues?labels[]=backend&labels[]=feature&labels[]=QA` +- To filter issues by `status`, specify the `status` parameter in the URL: + `/-/integrations/jira/issues?status=In Progress` - To filter issues by `reporter`, specify a reporter's Jira display name for the -`author_username` parameter in the URL. `/-/integrations/jira/issues?author_username=John Smith` - + `author_username` parameter in the URL: `/-/integrations/jira/issues?author_username=John Smith` - To filter issues by `assignee`, specify their Jira display name for the -`assignee_username` parameter in the URL. `/-/integrations/jira/issues?assignee_username=John Smith` + `assignee_username` parameter in the URL: `/-/integrations/jira/issues?assignee_username=John Smith` + +Enhancements to use these filters through the user interface +[are planned](https://gitlab.com/groups/gitlab-org/-/epics/3622). ## Automatic issue transitions > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/...) in GitLab 13.10. -In this mode the referenced Jira issue is transitioned to the next available status with a category of "Done". +When you configure automatic issue transitions, you can transition a referenced +Jira issue to the next available status with a category of **Done**. To configure +this setting: -See the [Configure GitLab](development_panel.md#configure-gitlab) section, check the **Enable Jira transitions** setting and select the **Move to Done** option. +1. Refer to the [Configure GitLab](development_panel.md#configure-gitlab) instructions. +1. Select the **Enable Jira transitions** check box. +1. Select the **Move to Done** option. ## Custom issue transitions -For advanced workflows you can specify custom Jira transition IDs. +For advanced workflows, you can specify custom Jira transition IDs: -See the [Configure GitLab](development_panel.md#configure-gitlab) section, check the **Enable Jira transitions** setting, select the **Custom transitions** option, and enter your transition IDs in the text field. +1. Use the method based on your Jira subscription status: + - *(For users of Jira Cloud)* Obtain your transition IDs by editing a workflow + in the **Text** view. The transition IDs display in the **Transitions** column. + - *(For users of Jira Server)* Obtain your transition IDs in one of these ways: + - By using the API, with a request like `https://yourcompany.atlassian.net/rest/api/2/issue/ISSUE-123/transitions`, + using an issue that is in the appropriate "open" state. + - By mousing over the link for the transition you want and looking for the + **action** parameter in the URL. + The transition ID may vary between workflows (for example, a bug instead of a + story), even if the status you're changing to is the same. +1. Refer to the [Configure GitLab](development_panel.md#configure-gitlab) instructions. +1. Select the **Enable Jira transitions** setting. +1. Select the **Custom transitions** option. +1. Enter your transition IDs in the text field. If you insert multiple transition IDs + (separated by `,` or `;`), the issue is moved to each state, one after another, in the + order you specify. If a transition fails, the sequence is aborted. -If you insert multiple transition IDs separated by `,` or `;`, the issue is moved to each state, one after another, using the given order. If a transition fails the sequence is aborted. +## Disable comments on Jira issues -To see the transition IDs on Jira Cloud, edit a workflow in the **Text** view. -The transition IDs display in the **Transitions** column. +GitLab can cross-link source commits or merge requests with Jira issues without +adding a comment to the Jira issue: -On Jira Server you can get the transition IDs in either of the following ways: +1. Refer to the [Configure GitLab](development_panel.md#configure-gitlab) instructions. +1. Clear the **Enable comments** check box. -1. By using the API, with a request like `https://yourcompany.atlassian.net/rest/api/2/issue/ISSUE-123/transitions` - using an issue that is in the appropriate "open" state -1. By mousing over the link for the transition you want and looking for the - "action" parameter in the URL +## Enable or disable the ability to require an associated Jira issue on merge requests -Note that the transition ID may vary between workflows (for example, bug vs. story), -even if the status you are changing to is the same. +The ability to require an associated Jira issue on merge requests is under development +and not ready for production use. It is deployed behind a feature flag that is +**disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) can enable it. -## Disabling comments on Jira issues +To enable it: -You can continue to have GitLab cross-link a source commit/MR with a Jira issue while disabling the comment added to the issue. +```ruby +Feature.enable(:jira_issue_association_on_merge_request) +``` + +To disable it: -See the [Configure GitLab](development_panel.md#configure-gitlab) section and uncheck the **Enable comments** setting. +```ruby +Feature.disable(:jira_issue_association_on_merge_request) +``` |