Add latest changes from gitlab-org/gitlab@master

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
 
 ![Delete source branch status](img/remove_source_branch_status.png)
 
+### 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)
+```