diff options
Diffstat (limited to 'doc/integration/jira/issues.md')
| -rw-r--r-- | doc/integration/jira/issues.md | 121 |
1 files changed, 78 insertions, 43 deletions
diff --git a/doc/integration/jira/issues.md b/doc/integration/jira/issues.md index 3a5d8e66b2d..086d478ac15 100644 --- a/doc/integration/jira/issues.md +++ b/doc/integration/jira/issues.md @@ -1,58 +1,59 @@ --- stage: Manage -group: Integrations +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Jira integration issue management **(FREE)** +# Jira issue management **(FREE)** -Integrating issue management with Jira requires you to [configure Jira](index.md#jira-integration) -and [enable the Jira integration](configure.md) 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. +You can [manage Jira issues directly in GitLab](configure.md). +You can then refer to Jira issues by ID in GitLab commits and merge requests. +The Jira issue IDs must be in uppercase. -The Jira integration requires to you format any Jira issue IDs in uppercase. - -## Reference Jira issues +## Cross-reference GitLab activity and Jira issues 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. +GitLab issues, merge requests, and Git. +When you mention a Jira issue in a GitLab issue, merge request, comment, or commit: + +- GitLab links to the Jira issue from the mention in GitLab. +- GitLab adds a formatted comment to the Jira issue that links back to the issue, merge request, or commit in GitLab. -For example, this commit references the Jira issue `GIT-1`: +For example, when this commit refers to a `GIT-1` Jira issue: ```shell git commit -m "GIT-1 this is a test commit" ``` -GitLab adds a reference to the **Issue Links** section of Jira issue `GIT-1`: +GitLab adds to that Jira issue: - +- A reference in the **Web links** section +- A comment in the **Activity** section that follows this format: -GitLab also adds a comment to the issue, and uses this format: + ```plaintext + USER mentioned this issue in RESOURCE_NAME of [PROJECT_NAME|COMMENTLINK]: + ENTITY_TITLE + ``` -```plaintext -USER mentioned this issue in RESOURCE_NAME of [PROJECT_NAME|COMMENTLINK]: -ENTITY_TITLE -``` + - `USER`: Name of the user who has mentioned the Jira issue with a link to their GitLab user profile. + - `RESOURCE_NAME`: Type of resource (for example, a GitLab commit, issue, or merge request) that has referenced the Jira issue. + - `PROJECT_NAME`: GitLab project name. + - `COMMENTLINK`: Link to where the Jira issue is mentioned. + - `ENTITY_TITLE`: Title of the GitLab commit (first line), issue, or merge request. -- `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. +Only a single cross-reference comment appears in Jira per GitLab issue, merge request, or commit. +For example, multiple comments on a GitLab merge request that reference a Jira issue +create only a single cross-reference comment back to that merge request in Jira. You can [disable comments](#disable-comments-on-jira-issues) on issues. ### Require associated Jira issue for merge requests to be merged **(ULTIMATE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/280766) in GitLab 13.12, disabled behind `jira_issue_association_on_merge_request` [feature flag](../../administration/feature_flags.md). -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61722) in GitLab 14.1. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/335280) in GitLab 14.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/280766) in GitLab 13.12 [with a flag](../../administration/feature_flags.md) named `jira_issue_association_on_merge_request`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/335280) in GitLab 14.2. Feature flag `jira_issue_association_on_merge_request` removed. -You can prevent merge requests from being merged if they do not refer to a Jira issue. -To enforce this: +With this integration, you can prevent merge requests from being merged if they do not refer to a Jira issue. +To enable this feature: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Merge requests**. @@ -63,6 +64,41 @@ After you enable this feature, a merge request that doesn't reference an associa 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.** +## Customize Jira issue matching in GitLab + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112826) in GitLab 15.10. + +You can configure custom rules for how GitLab matches Jira issue keys by defining: + +- [A regex pattern](#use-regular-expression) +- [A prefix](#use-a-prefix) + +When you don't configure custom rules, the [default behavior](https://gitlab.com/gitlab-org/gitlab/-/blob/710d83af298d8896f2b940faf48a46d2feb4cbaf/lib/gitlab/regex.rb#L552) is used. For more information, see the [RE2 wiki](https://github.com/google/re2/wiki/Syntax). + +### Use regular expression + +To define a regex pattern for Jira issue keys: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Jira**. +1. Go to the **Jira issue matching** section. +1. In the **Jira issue regex** text box, enter a regex pattern. +1. Select **Save changes**. + +For more information, see the [Atlassian documentation](https://confluence.atlassian.com/adminjiraserver073/changing-the-project-key-format-861253229.html). + +### Use a prefix + +To define a prefix for Jira issue keys: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Jira**. +1. Go to the **Jira issue matching** section. +1. In the **Jira issue prefix** text box, enter a prefix. +1. Select **Save changes**. + ## Close Jira issues in GitLab If you have configured GitLab transition IDs, you can close a Jira issue directly @@ -79,7 +115,7 @@ For example, use any of these trigger words to close the Jira issue `PROJECT-1`: - `Fixes PROJECT-1` 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). +You can change your project's default branch in [project settings](../../user/project/settings/index.md). ### Use case for closing issues @@ -89,8 +125,7 @@ Consider this example: 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 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). @@ -98,19 +133,19 @@ Consider this example: > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3622) in GitLab 13.2. -You can browse, search, and view issues from a selected Jira project directly in GitLab, -if your GitLab administrator [has configured it](configure.md). +You can view and search issues from a selected Jira project directly in GitLab, +provided your GitLab administrator [has configured the integration](configure.md#configure-the-integration). -To do this, in GitLab, go to your project and select **Issues > Jira issues**. The issue list -sorts by **Created date** by default, with the newest issues listed at the top: +To view Jira issues: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Issues > Jira issues**. - +The issues are sorted by **Created date** by default, with the most recently created issues listed at the top. - To display the most recently updated issues first, select **Updated date**. -- 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: -  +- You can [search and filter the issue list](#search-and-filter-the-issue-list). +- In GitLab 13.10 and later, you can [select an issue from the list to view the issue in GitLab](https://gitlab.com/gitlab-org/gitlab/-/issues/299832). Issues are grouped into tabs based on their [Jira status](https://confluence.atlassian.com/adminjiraserver070/defining-status-field-values-749382903.html): @@ -119,7 +154,7 @@ Issues are grouped into tabs based on their - **Closed** tab: All issues with a Jira status categorized as Done. - **All** tab: All issues of any status. -### Search and filter the issues list **(PREMIUM)** +### Search and filter the issue list **(PREMIUM)** To refine the list of issues, use the search bar to search for any text contained in an issue summary (title) or description. Use any combination |