diff options
Diffstat (limited to 'doc/user/project')
| -rw-r--r-- | doc/user/project/integrations/jira.md | 60 | ||||
| -rw-r--r-- | doc/user/project/integrations/jira_integrations.md | 1 | ||||
| -rw-r--r-- | doc/user/project/merge_requests/getting_started.md | 46 |
3 files changed, 85 insertions, 22 deletions
diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index aa5d11282d9..5857c3da803 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -32,7 +32,8 @@ completed in GitLab and: - The Jira issue shows the status of the deployment (in the sidebar as "deployments"). - Create or modify a feature flag that mentions a Jira issue in its description: - The Jira issue shows the details of the feature-flag (in the sidebar as "feature flags"). -- View a list of Jira issues directly in GitLab **(PREMIUM)** +- View a list of Jira issues directly in GitLab. **(PREMIUM)** +- Create a Jira issue from a vulnerability. **(ULTIMATE)** Additional features provided by the Jira Development Panel integration include: @@ -90,37 +91,52 @@ Atlassian cloud, an **email and API token** are required. For more information, > to enable Basic Auth. The cookie being added to each request is `OBBasicAuth` with > a value of `fromDialog`. -To enable the Jira integration in a project, navigate to the -[Integrations page](overview.md#accessing-integrations) and click -the **Jira** service. +To enable the Jira integration in a project: -Select **Enable integration**. +1. Go to the project's [Integrations page](overview.md#accessing-integrations) and select the + **Jira** service. -Select a **Trigger** action. This determines whether a mention of a Jira issue in GitLab commits, merge requests, or both, should link the Jira issue back to that source commit/MR and transition the Jira issue, if indicated. +1. Select **Enable integration**. -To include a comment on the Jira issue when the above reference is made in GitLab, check **Enable comments**. +1. Select **Trigger** actions. + This determines whether a mention of a Jira issue in GitLab commits, merge requests, or both, + should link the Jira issue back to that source commit/MR and transition the Jira issue, if + indicated. -Enter the further details on the page as described in the following table. +1. To include a comment on the Jira issue when the above reference is made in GitLab, select + **Enable comments**. -| Field | Description | -| ----- | ----------- | -| `Web URL` | The base URL to the Jira instance web interface which is being linked to this GitLab project. For example, `https://jira.example.com`. | -| `Jira API URL` | The base URL to the Jira instance API. Web URL value is used if not set. For example, `https://jira-api.example.com`. Leave this field blank (or use the same value of `Web URL`) if using **Jira on Atlassian cloud**. | -| `Username or Email` | Created in [configure Jira](#configure-jira) step. Use `username` for **Jira Server** or `email` for **Jira on Atlassian cloud**. | -| `Password/API token` |Created in [configure Jira](#configure-jira) step. Use `password` for **Jira Server** or `API token` for **Jira on Atlassian cloud**. | -| `Jira workflow transition IDs` | Required for closing Jira issues via commits or merge requests. These are the IDs of transitions in Jira that move issues to a particular state. (See [Obtaining a transition ID](#obtaining-a-transition-id).) If you insert multiple transition IDs separated by `,` or `;`, the issue is moved to each state, one after another, using the given order. In GitLab 13.6 and earlier, field was called `Transition ID`. | + 1. Select the **Comment detail**: **Standard** or **All details**. -To enable users to view Jira issues inside the GitLab project, select **Enable Jira issues** and enter a Jira project key. **(PREMIUM)** +1. Enter the further details on the page as described in the following table. -You can only display issues from a single Jira project within a given GitLab project. + | Field | Description | + | ----- | ----------- | + | `Web URL` | The base URL to the Jira instance web interface which is being linked to this GitLab project. For example, `https://jira.example.com`. | + | `Jira API URL` | The base URL to the Jira instance API. Web URL value is used if not set. For example, `https://jira-api.example.com`. Leave this field blank (or use the same value of `Web URL`) if using **Jira on Atlassian cloud**. | + | `Username or Email` | Created in [configure Jira](#configure-jira) step. Use `username` for **Jira Server** or `email` for **Jira on Atlassian cloud**. | + | `Password/API token` | Created in [configure Jira](#configure-jira) step. Use `password` for **Jira Server** or `API token` for **Jira on Atlassian cloud**. | + | `Jira workflow transition IDs` | Required for closing Jira issues via commits or merge requests. These are the IDs of transitions in Jira that move issues to a particular state. (See [Obtaining a transition ID](#obtaining-a-transition-id).) If you insert multiple transition IDs separated by `,` or `;`, the issue is moved to each state, one after another, using the given order. In GitLab 13.6 and earlier, field was called `Transition ID`. | -WARNING: -If you enable Jira issues with the setting above, all users that have access to this GitLab project -are able to view all issues from the specified Jira project. +1. To enable users to view Jira issues inside the GitLab project, select **Enable Jira issues** and + enter a Jira project key. **(PREMIUM)** -When you have configured all settings, click **Test settings and save changes**. + You can only display issues from a single Jira project within a given GitLab project. -Your GitLab project can now interact with all Jira projects in your instance and the project now displays a Jira link that opens the Jira project. + WARNING: + If you enable Jira issues with the setting above, all users that have access to this GitLab project + are able to view all issues from the specified Jira project. + +1. To enable creation of issues for vulnerabilities, select **Enable Jira issues creation from vulnerabilities**. + + 1. Select the **Jira issue type**. If the dropdown is empty, select refresh (**{retry}**) and try again. + +1. To verify the Jira connection is working, select **Test settings**. + +1. Select **Save changes**. + +Your GitLab project can now interact with all Jira projects in your instance and the project now +displays a Jira link that opens the Jira project. #### Obtaining a transition ID diff --git a/doc/user/project/integrations/jira_integrations.md b/doc/user/project/integrations/jira_integrations.md index 3daea250aac..6a1529f001a 100644 --- a/doc/user/project/integrations/jira_integrations.md +++ b/doc/user/project/integrations/jira_integrations.md @@ -53,3 +53,4 @@ time. | Record Jira time tracking information against an issue | No | Yes. Time can be specified via Jira Smart Commits. | | Transition or close a Jira issue with a Git commit or merge request | Yes. Only a single transition type, typically configured to close the issue by setting it to Done. | Yes. Transition to any state using Jira Smart Commits. | | Display a list of Jira issues | Yes **(PREMIUM)** | No | +| Create a Jira issue from a vulnerability or finding **(ULTIMATE)** | Yes | No | diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 92db8bb2618..b1a57d9c3e6 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -194,6 +194,33 @@ is set for deletion, the merge request widget displays the  +### Branch retargeting on merge **(FREE SELF)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/320902) in GitLab 13.9. +> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. +> - It's disabled on GitLab.com. +> - It's not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-branch-retargeting-on-merge). + +In specific circumstances, GitLab can retarget the destination branch of +open merge request, if the destination branch merges while the merge request is +open. Merge requests are often chained in this manner, with one merge request +depending on another: + +- **Merge request 1**: merge `feature-alpha` into `master`. +- **Merge request 2**: merge `feature-beta` into `feature-alpha`. + +These merge requests are usually handled in one of these ways: + +- Merge request 1 is merged into `master` first. Merge request 2 is then + retargeted to `master`. +- Merge request 2 is merged into `feature-alpha`. The updated merge request 1, which + now contains the contents of `feature-alpha` and `feature-beta`, is merged into `master`. + +GitLab retargets up to four merge requests when their target branch is merged into +`master`, so you don't need to perform this operation manually. Merge requests from +forks are not retargeted. + ## Recommendations and best practices for Merge Requests - When working locally in your branch, add multiple commits and only push when @@ -230,3 +257,22 @@ Feature.disable(:reviewer_approval_rules) # For a single project Feature.disable(:reviewer_approval_rules, Project.find(<project id>)) ``` + +### Enable or disable branch retargeting on merge **(FREE SELF)** + +Automatically retargeting merge requests is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can opt to disable it. + +To enable it: + +```ruby +Feature.enable(:retarget_merge_requests) +``` + +To disable it: + +```ruby +Feature.disable(:retarget_merge_requests) +``` |