diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2022-05-19 07:33:21 +0000 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2022-05-19 07:33:21 +0000 |
| commit | 36a59d088eca61b834191dacea009677a96c052f (patch) | |
| tree | e4f33972dab5d8ef79e3944a9f403035fceea43f /doc/user/project/merge_requests | |
| parent | a1761f15ec2cae7c7f7bbda39a75494add0dfd6f (diff) | |
| download | gitlab-ce-36a59d088eca61b834191dacea009677a96c052f.tar.gz | |
Add latest changes from gitlab-org/gitlab@15-0-stable-eev15.0.0-rc42
Diffstat (limited to 'doc/user/project/merge_requests')
23 files changed, 262 insertions, 192 deletions
diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index 5826ebcab49..d06c8182e22 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -60,10 +60,10 @@ In the following example: To change or add a commit to the contributor's merge request: -1. Open the merge request page, and select the **Overview** tab. -1. Scroll to the merge request widget, and select **Check out branch**. +1. Go to the merge request. +1. In the upper right corner, select **Code**, then select **Check out branch**. 1. In the modal window, select **Copy** (**{copy-to-clipboard}**). -1. In your terminal, navigate to your cloned version of the repository, and +1. In your terminal, go to your cloned version of the repository, and paste the commands. For example: ```shell diff --git a/doc/user/project/merge_requests/approvals/img/security_approvals_v15_0.png b/doc/user/project/merge_requests/approvals/img/security_approvals_v15_0.png Binary files differnew file mode 100644 index 00000000000..b28d216f180 --- /dev/null +++ b/doc/user/project/merge_requests/approvals/img/security_approvals_v15_0.png diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index e940426dc67..f0ab4d606ad 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -102,8 +102,8 @@ Without the approvals, the work cannot merge. Required approvals enable multiple - Use the [code owners of changed files](rules.md#code-owners-as-eligible-approvers), to determine who should review the work. - Require an [approval before merging code that causes test coverage to decline](../../../../ci/pipelines/settings.md#coverage-check-approval-rule) -- [Require approval from a security team](../../../application_security/index.md#security-approvals-in-merge-requests) - before merging code that could introduce a vulnerability. +- Users on GitLab Ultimate can also [require approval from a security team](../../../application_security/index.md#security-approvals-in-merge-requests) + before merging code that could introduce a vulnerability. ## Related topics diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index 01772e59127..17a42e1b540 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -242,3 +242,14 @@ the API. For more information about this validation error, read [issue 285129](https://gitlab.com/gitlab-org/gitlab/-/issues/285129). + +## Security Approvals **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357021) in GitLab 15.0. + +You can use [scan result policies](../../../application_security/policies/scan-result-policies.md#scan-result-policy-editor) to define security approvals based on the status of vulnerabilities in the merge request and the default branch. +Details for each security policy is shown in the Security Approvals section of your Merge Request configuration. + + + +These policies are both created and edited in the [security policy editor](../../../application_security/policies/index.md#policy-editor). diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index 0ede9310393..9c2b54888fb 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -119,16 +119,9 @@ when more changes are added to it: 1. Select the **Remove all approvals when commits are added to the source branch** checkbox. 1. Select **Save changes**. -Approvals aren't reset when a merge request is [rebased from the UI](../fast_forward_merge.md) +Approvals aren't reset when a merge request is [rebased from the UI](../methods/index.md#rebasing-in-semi-linear-merge-methods) However, approvals are reset if the target branch is changed. -## Security approvals in merge requests **(ULTIMATE)** - -You can require that a member of your security team approves a merge request if a -merge request could introduce a vulnerability. - -To learn more, see [Security approvals in merge requests](../../../application_security/index.md#security-approvals-in-merge-requests). - ## Code coverage check approvals You can require specific approvals if a merge request would result in a decline in code test diff --git a/doc/user/project/merge_requests/changes.md b/doc/user/project/merge_requests/changes.md index 8796ea0635b..5016a33ed28 100644 --- a/doc/user/project/merge_requests/changes.md +++ b/doc/user/project/merge_requests/changes.md @@ -14,7 +14,7 @@ changes. By default, the diff view compares the versions of files in the merge request source branch to the files in the target branch, and shows only the parts of a file that have changed. - + ## Show all changes in a merge request diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 10fc778d5ae..7e8ef9272d4 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -72,7 +72,7 @@ This example shows how to run Code Quality on your code by using GitLab CI/CD an In either configuration, the runner must have enough disk space to handle generated Code Quality files. For example on the [GitLab project](https://gitlab.com/gitlab-org/gitlab) the files are approximately 7 GB. -Once you set up GitLab Runner, include the Code Quality template in your CI configuration: +Once you set up GitLab Runner, include the [Code Quality template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Code-Quality.gitlab-ci.yml) in your CI configuration: ```yaml include: @@ -257,9 +257,9 @@ The template has these [`rules`](../../../ci/yaml/index.md#rules) for the `code ```yaml code_quality: rules: - - if: '$CODE_QUALITY_DISABLED' + - if: $CODE_QUALITY_DISABLED when: never - - if: '$CI_COMMIT_TAG || $CI_COMMIT_BRANCH' + - if: $CI_COMMIT_TAG || $CI_COMMIT_BRANCH ``` If you are using merge request pipelines, your `rules` (or [`workflow: rules`](../../../ci/yaml/index.md#workflow)) @@ -268,9 +268,9 @@ might look like this example: ```yaml job1: rules: - - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' # Run job1 in merge request pipelines - - if: '$CI_COMMIT_BRANCH == "main"' # Run job1 in pipelines on the main branch (but not in other branch pipelines) - - if: '$CI_COMMIT_TAG' # Run job1 in pipelines for tags + - if: $CI_PIPELINE_SOURCE == "merge_request_event" # Run job1 in merge request pipelines + - if: $CI_COMMIT_BRANCH == "main" # Run job1 in pipelines on the main branch (but not in other branch pipelines) + - if: $CI_COMMIT_TAG # Run job1 in pipelines for tags ``` To make these work together, you need to overwrite the code quality `rules` @@ -282,11 +282,11 @@ include: code_quality: rules: - - if: '$CODE_QUALITY_DISABLED' + - if: $CODE_QUALITY_DISABLED when: never - - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' # Run code quality job in merge request pipelines - - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH' # Run code quality job in pipelines on the default branch (but not in other branch pipelines) - - if: '$CI_COMMIT_TAG' # Run code quality job in pipelines for tags + - if: $CI_PIPELINE_SOURCE == "merge_request_event" # Run code quality job in merge request pipelines + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run code quality job in pipelines on the default branch (but not in other branch pipelines) + - if: $CI_COMMIT_TAG # Run code quality job in pipelines for tags ``` ### Configure Code Quality to use a private container image registry @@ -541,7 +541,7 @@ This can be due to multiple reasons: - If no [degradation or error is detected](https://docs.codeclimate.com/docs/maintainability#section-checks), nothing is displayed. - The [`artifacts:expire_in`](../../../ci/yaml/index.md#artifactsexpire_in) CI/CD - setting can cause the Code Quality artifact(s) to expire faster than desired. + setting can cause the Code Quality artifacts to expire faster than desired. - The widgets use the pipeline of the latest commit to the target branch. If commits are made to the default branch that do not run the code quality job, this may cause the merge request widget to have no base report for comparison. - If you use the [`REPORT_STDOUT` environment variable](https://gitlab.com/gitlab-org/ci-cd/codequality#environment-variables), no report file is generated and nothing displays in the merge request. - Large `gl-code-quality-report.json` files (esp. >10 MB) are [known to prevent the report from being displayed](https://gitlab.com/gitlab-org/gitlab/-/issues/2737). diff --git a/doc/user/project/merge_requests/confidential.md b/doc/user/project/merge_requests/confidential.md index 6900880417f..5b17ec009e4 100644 --- a/doc/user/project/merge_requests/confidential.md +++ b/doc/user/project/merge_requests/confidential.md @@ -74,5 +74,5 @@ Open a merge request - [Confidential issues](../issues/confidential_issues.md) - [Make an epic confidential](../../group/epics/manage_epics.md#make-an-epic-confidential) -- [Mark a comment as confidential](../../discussions/index.md#mark-a-comment-as-confidential) +- [Add an internal note](../../discussions/index.md#add-an-internal-note) - [Security practices for confidential merge requests](https://gitlab.com/gitlab-org/release/docs/blob/master/general/security/developer.md#security-releases-critical-non-critical-as-a-developer) at GitLab diff --git a/doc/user/project/merge_requests/fast_forward_merge.md b/doc/user/project/merge_requests/fast_forward_merge.md index 77162aa0b83..048421a3a5b 100644 --- a/doc/user/project/merge_requests/fast_forward_merge.md +++ b/doc/user/project/merge_requests/fast_forward_merge.md @@ -1,74 +1,11 @@ --- -stage: Create -group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: reference, concepts +redirect_to: 'methods/index.md' +remove_date: '2022-08-09' --- -# Fast-forward merge requests **(FREE)** +This document was moved to [another location](methods/index.md). -Sometimes, a workflow policy might mandate a clean commit history without -merge commits. In such cases, the fast-forward merge is the perfect candidate. - -With fast-forward merge requests, you can retain a linear Git history and a way -to accept merge requests without creating merge commits. - -When the fast-forward merge -([`--ff-only`](https://git-scm.com/docs/git-merge#git-merge---ff-only)) setting -is enabled, no merge commits are created and all merges are fast-forwarded, -which means that merging is only allowed if the branch can be fast-forwarded. - -When a fast-forward merge is not possible, the user is given the option to rebase. - -NOTE: -Projects using the fast-forward merge strategy can't filter merge requests -[by deployment date](../../search/index.md#filtering-merge-requests-by-environment-or-deployment-date), -because no merge commit is created. - -## Enabling fast-forward merges - -1. On the top bar, select **Menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. -1. Expand **Merge requests**. -1. In the **Merge method** section, select **Fast-forward merge**. -1. Select **Save changes**. - -Now, when you visit the merge request page, you can accept it -**only if a fast-forward merge is possible**. - - - -If a fast-forward merge is not possible but a conflict free rebase is possible, -a rebase button is offered. - -You can also rebase without running a CI/CD pipeline. -[Introduced in](https://gitlab.com/gitlab-org/gitlab/-/issues/118825) GitLab 14.7. - -The rebase action is also available as a [quick action command: `/rebase`](../../../topics/git/git_rebase.md#rebase-from-the-gitlab-ui). - - - -If the target branch is ahead of the source branch and a conflict free rebase is -not possible, you need to rebase the -source branch locally before you can do a fast-forward merge. - - - -## Fast-forward merges prevent squashing commits - -If your project has enabled fast-forward merges, to merge cleanly, the code in a -merge request cannot use [squashing during merge](squash_and_merge.md). Squashing -is available only when accepting a merge request. Rebasing may be required before -squashing, even though squashing can itself be considered equivalent to rebasing. - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +<!-- This redirect file can be deleted after <2022-08-09>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index fd1751585d5..c1986a80ca0 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -51,9 +51,9 @@ Learn the various ways to [create a merge request](creating_merge_requests.md). When you start a new merge request, you can immediately include the following options. You can also add them later by either selecting **Edit** on the merge request's page at the top-right side, or by using -[keyboard shortcuts for merge requests](../../shortcuts.md#issues-and-merge-requests): +[keyboard shortcuts for merge requests](../../shortcuts.md#merge-requests): -- [Assign](#assignee) the merge request to a colleague for review. With [multiple assignees](#multiple-assignees), you can assign it to more than one person at a time. +- [Assign](index.md#assign-a-user-to-a-merge-request) the merge request to a colleague for review. With [multiple assignees](index.md#assign-multiple-users), you can assign it to more than one person at a time. - Set a [milestone](../milestones/index.md) to track time-sensitive changes. - Add [labels](../labels.md) to help contextualize and filter your merge requests over time. - [Require approval](approvals/index.md#required-approvals) from your team. @@ -76,43 +76,11 @@ After you have created the merge request, you can also: Many of these options can be set: -- From the merge request page, with [keyboard shortcuts](../../shortcuts.md#issues-and-merge-requests). +- From the merge request page, with [keyboard shortcuts](../../shortcuts.md#merge-requests). - When pushing changes from the command line, with [Git push options](../push_options.md). See also other [features associated to merge requests](reviews/index.md#associated-features). -### Assignee - -Choose an assignee to designate someone as the person responsible -for the first [review of the merge request](reviews/index.md). -Open the drop down box to search for the user you wish to assign, -and the merge request is added to their -[assigned merge request list](../../search/index.md#search-issues-and-merge-requests). - -#### Multiple assignees **(PREMIUM)** - -> Moved to GitLab Premium in 13.9 - -Multiple people often review merge requests at the same time. -GitLab allows you to have multiple assignees for merge requests -to indicate everyone that is reviewing or accountable for it. - - - -To assign multiple assignees to a merge request: - -1. From a merge request, expand the right sidebar and locate the **Assignees** section. -1. Click on **Edit** and from the dropdown menu, select as many users as you want - to assign the merge request to. - -Similarly, assignees are removed by deselecting them from the same -dropdown menu. - -It is also possible to manage multiple assignees: - -- When creating a merge request. -- Using [quick actions](../quick_actions.md#issues-merge-requests-and-epics). - ### Reviewer WARNING: diff --git a/doc/user/project/merge_requests/img/merge_method_ff_v15_0.png b/doc/user/project/merge_requests/img/merge_method_ff_v15_0.png Binary files differnew file mode 100644 index 00000000000..323fd03ffa2 --- /dev/null +++ b/doc/user/project/merge_requests/img/merge_method_ff_v15_0.png diff --git a/doc/user/project/merge_requests/img/merge_method_merge_commit_v15_0.png b/doc/user/project/merge_requests/img/merge_method_merge_commit_v15_0.png Binary files differnew file mode 100644 index 00000000000..b880c2c0e04 --- /dev/null +++ b/doc/user/project/merge_requests/img/merge_method_merge_commit_v15_0.png diff --git a/doc/user/project/merge_requests/img/merge_method_merge_commit_with_semi_linear_history_v15_0.png b/doc/user/project/merge_requests/img/merge_method_merge_commit_with_semi_linear_history_v15_0.png Binary files differnew file mode 100644 index 00000000000..9eab71e9d3c --- /dev/null +++ b/doc/user/project/merge_requests/img/merge_method_merge_commit_with_semi_linear_history_v15_0.png diff --git a/doc/user/project/merge_requests/img/mr-diff-example_v14_8.png b/doc/user/project/merge_requests/img/mr-diff-example_v14_8.png Binary files differdeleted file mode 100644 index 1984defde9a..00000000000 --- a/doc/user/project/merge_requests/img/mr-diff-example_v14_8.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/mr-diff-example_v15.png b/doc/user/project/merge_requests/img/mr-diff-example_v15.png Binary files differnew file mode 100644 index 00000000000..8fdf3935906 --- /dev/null +++ b/doc/user/project/merge_requests/img/mr-diff-example_v15.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index a3b9fb52f0d..510dcd82907 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -70,6 +70,72 @@ change and whether you need access to a development environment: - [Push changes from the command line](../../../gitlab-basics/start-using-git.md), if you are familiar with Git and the command line. +## Assign a user to a merge request + +When a merge request is created, it's assigned by default to the person who created it. +This person owns the merge request, but isn't responsible for [reviewing it](reviews/index.md). +To assign the merge request to someone else, use the `/assign @user` +[quick action](../quick_actions.md#issues-merge-requests-and-epics) in a text area in +a merge request, or: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests** and find your merge request. +1. On the right sidebar, expand the right sidebar and locate the **Assignees** section. +1. Select **Edit**. +1. Search for the user you want to assign, and select the user. + +The merge request is added to the user's +[assigned merge request list](../../search/index.md#search-issues-and-merge-requests). + +### Assign multiple users **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. + +GitLab enables multiple assignees for merge requests, if multiple people are +accountable for it: + + + +To assign multiple assignees to a merge request, use the `/assign @user` +[quick action](../quick_actions.md#issues-merge-requests-and-epics) in a text area, or: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests** and find your merge request. +1. On the right sidebar, expand the right sidebar and locate the **Assignees** section. +1. Select **Edit** and, from the dropdown list, select all users you want + to assign the merge request to. + +To remove an assignee, clear the user from the same dropdown list. + +## Close a merge request + +If you decide to permanently stop work on a merge request, +GitLab recommends you close the merge request rather than +[delete it](#delete-a-merge-request). The author and assignees of a merge request, and users with +Developer, Maintainer, or Owner [roles](../../permissions.md) in a project +can close merge requests in the project: + +1. Go to the merge request you want to close. +1. Scroll to the comment box at the bottom of the page. +1. Following the comment box, select **Close merge request**. + +GitLab closes the merge request, but preserves records of the merge request, +its comments, and any associated pipelines. + +### Delete a merge request + +GitLab recommends you close, rather than delete, merge requests. + +WARNING: +You cannot undo the deletion of a merge request. + +To delete a merge request: + +1. Sign in to GitLab as a user with the project Owner role. + Only users with this role can delete merge requests in a project. +1. Go to the merge request you want to delete, and select **Edit**. +1. Scroll to the bottom of the page, and select **Delete merge request**. + ## Request attention to a merge request > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343528) in GitLab 14.10 [with a flag](../../../administration/feature_flags.md) named `mr_attention_requests`. Disabled by default. @@ -117,35 +183,6 @@ only one attention request, which is synced across both duties. If the attention request is removed from you, either as an assignee or a reviewer, it is removed from both your duties. -## Close a merge request - -If you decide to permanently stop work on a merge request, -GitLab recommends you close the merge request rather than -[delete it](#delete-a-merge-request). The author and assignees of a merge request, and users with -Developer, Maintainer, or Owner [roles](../../permissions.md) in a project -can close merge requests in the project: - -1. Go to the merge request you want to close. -1. Scroll to the comment box at the bottom of the page. -1. Following the comment box, select **Close merge request**. - -GitLab closes the merge request, but preserves records of the merge request, -its comments, and any associated pipelines. - -### Delete a merge request - -GitLab recommends you close, rather than delete, merge requests. - -WARNING: -You cannot undo the deletion of a merge request. - -To delete a merge request: - -1. Sign in to GitLab as a user with the project Owner role. - Only users with this role can delete merge requests in a project. -1. Go to the merge request you want to delete, and select **Edit**. -1. Scroll to the bottom of the page, and select **Delete merge request**. - ## Merge request workflows For a software developer working in a team: diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index 7861e1e28fc..a5fff4a38be 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -189,7 +189,7 @@ review: paths: - review.env rules: - - if: '$CI_COMMIT_BRANCH' # Modify to match your pipeline rules, or use `only/except` if needed. + - if: $CI_COMMIT_BRANCH # Modify to match your pipeline rules, or use `only/except` if needed. load_performance: dependencies: @@ -197,5 +197,5 @@ load_performance: variables: K6_DOCKER_OPTIONS: '--env-file review.env' rules: - - if: '$CI_COMMIT_BRANCH' # Modify to match your pipeline rules, or use `only/except` if needed. + - if: $CI_COMMIT_BRANCH # Modify to match your pipeline rules, or use `only/except` if needed. ``` diff --git a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md index 256dde4fa17..ac1c61f2e72 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -50,7 +50,7 @@ You can prevent merge requests from being merged if: This works for both: - GitLab CI/CD pipelines -- Pipelines run from an [external CI integration](../integrations/overview.md#integrations-listing) +- Pipelines run from an [external CI integration](../integrations/index.md#available-integrations) As a result, [disabling GitLab CI/CD pipelines](../../../ci/enable_or_disable_ci.md) does not disable this feature, as it is possible to use pipelines from external @@ -81,13 +81,13 @@ it could allow code that fails tests to be merged: ```yaml branch-pipeline-job: rules: - - if: '$CI_PIPELINE_SOURCE == "push"' + - if: $CI_PIPELINE_SOURCE == "push" script: - echo "Code testing scripts here, for example." merge-request-pipeline-job: rules: - - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' + - if: $CI_PIPELINE_SOURCE == "merge_request_event" script: - echo "No tests run, but this pipeline always succeeds and enables merge." - echo true diff --git a/doc/user/project/merge_requests/methods/index.md b/doc/user/project/merge_requests/methods/index.md new file mode 100644 index 00000000000..adfa5288f81 --- /dev/null +++ b/doc/user/project/merge_requests/methods/index.md @@ -0,0 +1,116 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: reference, concepts +--- + +# Merge methods **(FREE)** + +The merge method you select for your project determines how the changes in your +merge requests are merged into an existing branch. + +## Configure a project's merge method + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Merge requests**. +1. In the **Merge method** section, select your desired merge method. +1. Select **Save changes**. + +## Merge commit + +This setting is the default. It always creates a separate merge commit, +even when using [squash](../squash_and_merge.md). An example commit graph generated using this merge method: + + + +- For regular merges, it is equivalent to the command `git merge --no-ff <source-branch>`. +- For squash merges, it squashes all commits in the source branch before merging it normally. It performs actions similar to: + + ```shell + git checkout `git merge-base <source-branch> <target-branch>` + git merge --squash <source-branch> + SOURCE_SHA=`git rev-parse HEAD` + git checkout <target-branch> + git merge --no-ff $SOURCE_SHA + ``` + +## Merge commit with semi-linear history + +A merge commit is created for every merge, but the branch is only merged if +a fast-forward merge is possible. This ensures that if the merge request build +succeeded, the target branch build also succeeds after the merge. An example commit graph generated using this merge method: + + + +When you visit the merge request page with `Merge commit with semi-linear history` +method selected, you can accept it **only if a fast-forward merge is possible**. +When a fast-forward merge is not possible, the user is given the option to rebase, see +[Rebasing in (semi-)linear merge methods](#rebasing-in-semi-linear-merge-methods). + +This method is equivalent to the same Git commands as in the **Merge commit** method. However, +if your source branch is based on an out-of-date version of the target branch (such as `main`), +you must rebase your source branch. +This merge method creates a cleaner-looking history, while still enabling you to +see where every branch began and was merged. + +## Fast-forward merge + +Sometimes, a workflow policy might mandate a clean commit history without +merge commits. In such cases, the fast-forward merge is appropriate. With +fast-forward merge requests, you can retain a linear Git history and a way +to accept merge requests without creating merge commits. An example commit graph +generated using this merge method: + + + +This method is equivalent to `git merge --ff <source-branch>` for regular merges, and to +`git merge -squash <source-branch>` for squash merges. + +When the fast-forward merge +([`--ff-only`](https://git-scm.com/docs/git-merge#git-merge---ff-only)) setting +is enabled, no merge commits are created and all merges are fast-forwarded, +which means that merging is only allowed if the branch can be fast-forwarded. +When a fast-forward merge is not possible, the user is given the option to rebase, see +[Rebasing in (semi-)linear merge methods](#rebasing-in-semi-linear-merge-methods). + +NOTE: +Projects using the fast-forward merge strategy can't filter merge requests +[by deployment date](../../../search/index.md#filtering-merge-requests-by-environment-or-deployment-date), +because no merge commit is created. + +When you visit the merge request page with `Fast-forward merge` +method selected, you can accept it **only if a fast-forward merge is possible**. + + + +## Rebasing in (semi-)linear merge methods + +> Rebasing without running a CI/CD pipeline [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118825) in GitLab 14.7. + +In these merge methods, you can merge only when your source branch is up-to-date with the target branch: + +- Merge commit with semi-linear history. +- Fast-forward merge. + +If a fast-forward merge is not possible but a conflict-free rebase is possible, +GitLab offers you the [`/rebase` quick action](../../../../topics/git/git_rebase.md#rebase-from-the-gitlab-ui), +and the ability to **Rebase** from the user interface: + + + +In [GitLab 14.7](https://gitlab.com/gitlab-org/gitlab/-/issues/118825) and later, you can also rebase without running a CI/CD pipeline. + +If the target branch is ahead of the source branch and a conflict-free rebase is +not possible, you must rebase the source branch locally before you can do a fast-forward merge. + + + +Rebasing may be required before squashing, even though squashing can itself be +considered equivalent to rebasing. + +## Related topics + +- [Commits history](../commits.md) +- [Squash and merge](../squash_and_merge.md) diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index 6441ccb73fe..7b4a41f9339 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -14,7 +14,7 @@ by clicking the **Revert** button in merge requests and commit details. NOTE: The **Revert** button is shown only for projects that use the merge method "Merge Commit", which can be set under the project's -**Settings > General > Merge request**. [Fast-forward commits](fast_forward_merge.md) +**Settings > General > Merge request**. [Fast-forward commits](methods/index.md#fast-forward-merge) can not be reverted by using the merge request view. After the merge request has been merged, use the **Revert** button diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index 512faae82a9..eb5a54e6119 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -131,17 +131,6 @@ the author of the merge request can request a new review from the reviewer: GitLab creates a new [to-do item](../../../todos.md) for the reviewer, and sends them a notification email. -## Semi-linear history merge requests - -A merge commit is created for every merge, but the branch is only merged if -a fast-forward merge is possible. This ensures that if the merge request build -succeeded, the target branch build also succeeds after the merge. - -1. Go to your project and select **Settings > General**. -1. Expand **Merge requests**. -1. In the **Merge method** section, select **Merge commit with semi-linear history**. -1. Select **Save changes**. - ## Comment on multiple lines > - [Introduced](https://gitlab.com/gitlab-org/ux-research/-/issues/870) in GitLab 13.2. @@ -211,17 +200,17 @@ These features are associated with merge requests: - [Cherry-pick changes](../cherry_pick_changes.md): Cherry-pick any commit in the UI by selecting the **Cherry-pick** button in a merged merge requests or a commit. -- [Fast-forward merge requests](../fast_forward_merge.md): +- [Fast-forward merge requests](../methods/index.md#fast-forward-merge): For a linear Git history and a way to accept merge requests without creating merge commits - [Find the merge request that introduced a change](../versions.md): - When viewing the commit details page, GitLab links to the merge request(s) containing that commit. + When viewing the commit details page, GitLab links to the merge requests containing that commit. - [Merge requests versions](../versions.md): Select and compare the different versions of merge request diffs - [Resolve conflicts](../conflicts.md): GitLab can provide the option to resolve certain merge request conflicts in the GitLab UI. - [Revert changes](../revert_changes.md): Revert changes from any commit from a merge request. -- [Keyboard shortcuts](../../../shortcuts.md#issues-and-merge-requests): +- [Keyboard shortcuts](../../../shortcuts.md#merge-requests): Access and modify specific parts of a merge request with keyboard commands. ## Troubleshooting @@ -365,3 +354,7 @@ All the above can be done with the [`git-mr`](https://gitlab.com/glensc/git-mr) In a group, the sidebar displays the total count of open merge requests. This value is cached if it's greater than than 1000. The cached value is rounded to thousands (or millions) and updated every 24 hours. + +## Related topics + +- [Merge methods](../methods/index.md) diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index a1d6959b75e..7e37990b9bf 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -18,8 +18,8 @@ in your Git repository by using the _squash and merge_ strategy. Each time a branch merges into your base branch, up to two commits are added: - The single commit created by squashing the commits from the branch. -- A merge commit, unless you have [enabled fast-forward merges](fast_forward_merge.md#enabling-fast-forward-merges) - in your project. Fast-forward merges disable both merge commits and squashing. +- A merge commit, unless you have enabled [fast-forward merges](methods/index.md#fast-forward-merge) + in your project. Fast-forward merges disable merge commits. By default, squashed commits contain the following metadata: @@ -74,7 +74,7 @@ To configure the default squashing behavior for all merge requests in your proje ## Related topics - [Commit message templates](commit_templates.md) -- [Fast-forward merges](fast_forward_merge.md) +- [Merge methods](methods/index.md) <!-- ## Troubleshooting diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index 9f1e5ae7046..85b5bbea284 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -28,7 +28,7 @@ between pipeline completion and the visualization loading on the page. For the coverage analysis to work, you have to provide a properly formatted [Cobertura XML](https://cobertura.github.io/cobertura/) report to -[`artifacts:reports:cobertura`](../../../ci/yaml/artifacts_reports.md#artifactsreportscobertura-deprecated). +[`artifacts:reports:coverage_report`](../../../ci/yaml/artifacts_reports.md#artifactsreportscoverage_report). This format was originally developed for Java, but most coverage analysis frameworks for other languages have plugins to add support for it, like: @@ -196,7 +196,9 @@ coverage-jdk11: needs: ["test-jdk11"] artifacts: reports: - cobertura: target/site/cobertura.xml + coverage_report: + coverage_format: cobertura + path: target/site/cobertura.xml ``` #### Gradle example @@ -232,7 +234,9 @@ coverage-jdk11: needs: ["test-jdk11"] artifacts: reports: - cobertura: build/cobertura.xml + coverage_report: + coverage_format: cobertura + path: build/cobertura.xml ``` ### Python example @@ -251,9 +255,12 @@ run tests: - coverage run -m pytest - coverage report - coverage xml + coverage: '/TOTAL.*\s([.\d]+)%/' artifacts: reports: - cobertura: coverage.xml + coverage_report: + coverage_format: cobertura + path: coverage.xml ``` ### PHP example @@ -263,7 +270,7 @@ to collect test coverage data and generate the report. With a minimal [`phpunit.xml`](https://phpunit.readthedocs.io/en/9.5/configuration.html) file (you may reference [this example repository](https://gitlab.com/yookoala/code-coverage-visualization-with-php/)), you can run the test and -generate the coverage xml: +generate the `coverage.xml`: ```yaml run tests: @@ -283,7 +290,9 @@ run tests: - php ./vendor/bin/phpunit --coverage-text --coverage-cobertura=coverage.cobertura.xml artifacts: reports: - cobertura: coverage.cobertura.xml + coverage_report: + coverage_format: cobertura + path: coverage.cobertura.xml ``` [Codeception](https://codeception.com/), through PHPUnit, also supports generating Cobertura report with @@ -318,7 +327,9 @@ run tests: name: ${CI_JOB_NAME}-${CI_COMMIT_REF_NAME}-${CI_COMMIT_SHA} expire_in: 2 days reports: - cobertura: build/coverage.xml + coverage_report: + coverage_format: cobertura + path: build/coverage.xml ``` ### Go example @@ -345,7 +356,9 @@ run tests: - go run github.com/boumenot/gocover-cobertura < coverage.txt > coverage.xml artifacts: reports: - cobertura: coverage.xml + coverage_report: + coverage_format: cobertura + path: coverage.xml ``` ### Ruby example @@ -372,5 +385,7 @@ run tests: - bundle exec rspec artifacts: reports: - cobertura: coverage/coverage.xml + coverage_report: + coverage_format: cobertura + path: coverage/coverage.xml ``` |
