diff options
Diffstat (limited to 'doc/user/project/merge_requests')
27 files changed, 322 insertions, 55 deletions
diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index ad1d79ae5b1..3a409bab19d 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -1,5 +1,6 @@ --- type: reference, howto +disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/code_quality_diff.html' --- # Code Quality **(STARTER)** @@ -9,8 +10,18 @@ in [GitLab Starter](https://about.gitlab.com/pricing/) 9.3. With the help of [GitLab CI/CD](../../../ci/README.md), you can analyze your source code quality using GitLab Code Quality. -Code Quality uses [Code Climate Engines](https://codeclimate.com), which are -free and open source. Code Quality doesn't require a Code Climate subscription. + +Code Quality: + +- Uses [Code Climate Engines](https://codeclimate.com), which are + free and open source. Code Quality doesn't require a Code Climate + subscription. +- Runs in [pipelines](../../../ci/pipelines.md) using an Docker image built in + [GitLab Code + Quality](https://gitlab.com/gitlab-org/security-products/codequality) project. +- Can make use of a [template](#template-and-examples). +- Is available with [Auto + DevOps](../../../topics/autodevops/index.md#auto-code-quality-starter). Going a step further, GitLab can show the Code Quality report right in the merge request widget area: @@ -21,22 +32,48 @@ in the merge request widget area: For instance, consider the following workflow: -1. Your backend team member starts a new implementation for making a certain feature in your app faster -1. With Code Quality reports, they analyze how their implementation is impacting the code quality -1. The metrics show that their code degrade the quality in 10 points -1. You ask a co-worker to help them with this modification -1. They both work on the changes until Code Quality report displays no degradations, only improvements -1. You approve the merge request and authorize its deployment to staging -1. Once verified, their changes are deployed to production +1. Your backend team member starts a new implementation for making a certain + feature in your app faster. +1. With Code Quality reports, they analyze how their implementation is impacting + the code quality. +1. The metrics show that their code degrade the quality in 10 points. +1. You ask a co-worker to help them with this modification. +1. They both work on the changes until Code Quality report displays no + degradations, only improvements. +1. You approve the merge request and authorize its deployment to staging. +1. Once verified, their changes are deployed to production. + +## Template and examples + +For most GitLab instances, the supplied template is the preferred method of +implementing Code Quality. See +[Analyze your project's Code Quality](../../../ci/examples/code_quality.md) for: + +- Information on the builtin GitLab Code Quality template. +- Examples of manual GitLab configuration for earlier GitLab versions. -## How it works +## Configuring jobs using variables -First of all, you need to define a job in your `.gitlab-ci.yml` file that generates the -[Code Quality report artifact](../../../ci/yaml/README.md#artifactsreportscodequality-starter). +The Code Quality job supports environment variables that users can set to +configure job execution at runtime. -The Code Quality report artifact is a subset of the -[Code Climate spec](https://github.com/codeclimate/spec/blob/master/SPEC.md#data-types). -It must be a JSON file containing an array of objects with the following properties: +For a list of available environment variables, see +[Environment variables](https://gitlab.com/gitlab-org/security-products/codequality/blob/master/README.md#environment-variables). + +## Implementing a custom tool + +It's possible to have a custom tool provide Code Quality reports in GitLab. To +do this: + +1. Define a job in your `.gitlab-ci.yml` file that generates the + [Code Quality report + artifact](../../../ci/yaml/README.md#artifactsreportscodequality-starter). +1. Configure your tool to generate the Code Quality report artifact as a JSON + file that implements subset of the [Code Climate + spec](https://github.com/codeclimate/spec/blob/master/SPEC.md#data-types). + +The Code Quality report artifact JSON file must contain an array of objects +with the following properties: | Name | Description | | ---------------------- | -------------------------------------------------------------------------------------- | @@ -63,13 +100,16 @@ Example: ``` NOTE: **Note:** -Although the Code Climate spec supports more properties, those are ignored by GitLab. +Although the Code Climate spec supports more properties, those are ignored by +GitLab. + +## Code Quality reports -For more information on what the Code Quality job should look like, check the -example on [analyzing a project's code quality](../../../ci/examples/code_quality.md). +Once the Code Quality job has completed, GitLab: -GitLab then checks this report, compares the metrics between the source and target -branches, and shows the information right on the merge request. +- Checks the generated report. +- Compares the metrics between the source and target branches. +- Shows the information right on the merge request. If multiple jobs in a pipeline generate a code quality artifact, only the artifact from the last created job (the job with the largest job ID) is used. To avoid confusion, diff --git a/doc/user/project/merge_requests/code_quality_diff.md b/doc/user/project/merge_requests/code_quality_diff.md index ccc694672a6..0aa108a2e73 100644 --- a/doc/user/project/merge_requests/code_quality_diff.md +++ b/doc/user/project/merge_requests/code_quality_diff.md @@ -1,5 +1,4 @@ --- -redirect_from: 'code_quality_diff.md' redirect_to: 'code_quality.md' --- diff --git a/doc/user/project/merge_requests/fast_forward_merge.md b/doc/user/project/merge_requests/fast_forward_merge.md index 4f3c68090e4..2d59e535ce1 100644 --- a/doc/user/project/merge_requests/fast_forward_merge.md +++ b/doc/user/project/merge_requests/fast_forward_merge.md @@ -15,7 +15,7 @@ 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 will be created and all merges are fast-forwarded, -which means that merging is only allowed if the branch could be 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. @@ -28,9 +28,15 @@ When a fast-forward merge is not possible, the user is given the option to rebas Now, when you visit the merge request page, you will be able to 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 will be offered. +  -If the target branch is ahead of the source branch, you need to rebase the +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 will be able to do a fast-forward merge.  diff --git a/doc/user/project/merge_requests/img/allow_collaboration.png b/doc/user/project/merge_requests/img/allow_collaboration.png Binary files differindex e40e8a6b11c..cc13493646d 100644 --- a/doc/user/project/merge_requests/img/allow_collaboration.png +++ b/doc/user/project/merge_requests/img/allow_collaboration.png diff --git a/doc/user/project/merge_requests/img/allow_collaboration_after_save.png b/doc/user/project/merge_requests/img/allow_collaboration_after_save.png Binary files differindex 4ba4c84c8c5..bc7678b21ec 100644 --- a/doc/user/project/merge_requests/img/allow_collaboration_after_save.png +++ b/doc/user/project/merge_requests/img/allow_collaboration_after_save.png diff --git a/doc/user/project/merge_requests/img/approvals_premium_mr_widget.png b/doc/user/project/merge_requests/img/approvals_premium_mr_widget.png Binary files differindex b6dc86f312e..2598cc71c33 100644 --- a/doc/user/project/merge_requests/img/approvals_premium_mr_widget.png +++ b/doc/user/project/merge_requests/img/approvals_premium_mr_widget.png diff --git a/doc/user/project/merge_requests/img/approvals_premium_project_edit.png b/doc/user/project/merge_requests/img/approvals_premium_project_edit.png Binary files differindex b6f6188b9cd..6a09412533f 100644 --- a/doc/user/project/merge_requests/img/approvals_premium_project_edit.png +++ b/doc/user/project/merge_requests/img/approvals_premium_project_edit.png diff --git a/doc/user/project/merge_requests/img/approvals_starter_project_edit.png b/doc/user/project/merge_requests/img/approvals_starter_project_edit.png Binary files differindex 868b9d58740..4c554d846cc 100644 --- a/doc/user/project/merge_requests/img/approvals_starter_project_edit.png +++ b/doc/user/project/merge_requests/img/approvals_starter_project_edit.png diff --git a/doc/user/project/merge_requests/img/approvals_starter_project_empty.png b/doc/user/project/merge_requests/img/approvals_starter_project_empty.png Binary files differindex 7375820224c..fc88a59a745 100644 --- a/doc/user/project/merge_requests/img/approvals_starter_project_empty.png +++ b/doc/user/project/merge_requests/img/approvals_starter_project_empty.png diff --git a/doc/user/project/merge_requests/img/approve.png b/doc/user/project/merge_requests/img/approve.png Binary files differindex e68259ac5c2..e2641f48c7a 100644 --- a/doc/user/project/merge_requests/img/approve.png +++ b/doc/user/project/merge_requests/img/approve.png diff --git a/doc/user/project/merge_requests/img/approve_additionally.png b/doc/user/project/merge_requests/img/approve_additionally.png Binary files differindex 3db5a9159e5..bab0cd4e041 100644 --- a/doc/user/project/merge_requests/img/approve_additionally.png +++ b/doc/user/project/merge_requests/img/approve_additionally.png diff --git a/doc/user/project/merge_requests/img/create_from_email.png b/doc/user/project/merge_requests/img/create_from_email.png Binary files differindex 5cb2afaf976..14eef473e27 100644 --- a/doc/user/project/merge_requests/img/create_from_email.png +++ b/doc/user/project/merge_requests/img/create_from_email.png diff --git a/doc/user/project/merge_requests/img/cross_project_dependencies_edit_inaccessible_v12_2.png b/doc/user/project/merge_requests/img/cross_project_dependencies_edit_inaccessible_v12_2.png Binary files differnew file mode 100644 index 00000000000..2dc02634fd8 --- /dev/null +++ b/doc/user/project/merge_requests/img/cross_project_dependencies_edit_inaccessible_v12_2.png diff --git a/doc/user/project/merge_requests/img/cross_project_dependencies_edit_v12_2.png b/doc/user/project/merge_requests/img/cross_project_dependencies_edit_v12_2.png Binary files differnew file mode 100644 index 00000000000..362e7e0ead2 --- /dev/null +++ b/doc/user/project/merge_requests/img/cross_project_dependencies_edit_v12_2.png diff --git a/doc/user/project/merge_requests/img/cross_project_dependencies_view_v12_2.png b/doc/user/project/merge_requests/img/cross_project_dependencies_view_v12_2.png Binary files differnew file mode 100644 index 00000000000..e00231c839b --- /dev/null +++ b/doc/user/project/merge_requests/img/cross_project_dependencies_view_v12_2.png diff --git a/doc/user/project/merge_requests/img/ff_merge_mr.png b/doc/user/project/merge_requests/img/ff_merge_mr.png Binary files differnew file mode 100644 index 00000000000..241cc990343 --- /dev/null +++ b/doc/user/project/merge_requests/img/ff_merge_mr.png diff --git a/doc/user/project/merge_requests/img/filter_approver_merge_requests.png b/doc/user/project/merge_requests/img/filter_approver_merge_requests.png Binary files differindex 9c386391a4f..4c28ee17f47 100644 --- a/doc/user/project/merge_requests/img/filter_approver_merge_requests.png +++ b/doc/user/project/merge_requests/img/filter_approver_merge_requests.png diff --git a/doc/user/project/merge_requests/img/filter_wip_merge_requests.png b/doc/user/project/merge_requests/img/filter_wip_merge_requests.png Binary files differindex 8df6a3c9a29..0989b41e2a4 100644 --- a/doc/user/project/merge_requests/img/filter_wip_merge_requests.png +++ b/doc/user/project/merge_requests/img/filter_wip_merge_requests.png diff --git a/doc/user/project/merge_requests/img/incrementally_expand_merge_request_diffs_v12_2.png b/doc/user/project/merge_requests/img/incrementally_expand_merge_request_diffs_v12_2.png Binary files differnew file mode 100644 index 00000000000..ee94dbdea5c --- /dev/null +++ b/doc/user/project/merge_requests/img/incrementally_expand_merge_request_diffs_v12_2.png diff --git a/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_only_if_succeeds_settings.png b/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_only_if_succeeds_settings.png Binary files differindex ea3aff59aa1..ed374b11fbd 100644 --- a/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_only_if_succeeds_settings.png +++ b/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_only_if_succeeds_settings.png diff --git a/doc/user/project/merge_requests/img/multiple_assignees_for_merge_requests_sidebar.png b/doc/user/project/merge_requests/img/multiple_assignees_for_merge_requests_sidebar.png Binary files differindex 9ae6e350798..dde2680ed74 100644 --- a/doc/user/project/merge_requests/img/multiple_assignees_for_merge_requests_sidebar.png +++ b/doc/user/project/merge_requests/img/multiple_assignees_for_merge_requests_sidebar.png diff --git a/doc/user/project/merge_requests/img/remove_approval.png b/doc/user/project/merge_requests/img/remove_approval.png Binary files differindex 6083e1745ef..b178d26cf85 100644 --- a/doc/user/project/merge_requests/img/remove_approval.png +++ b/doc/user/project/merge_requests/img/remove_approval.png diff --git a/doc/user/project/merge_requests/img/squash_mr_message.png b/doc/user/project/merge_requests/img/squash_mr_message.png Binary files differindex 8734cab29aa..8c7dc7886f7 100644 --- a/doc/user/project/merge_requests/img/squash_mr_message.png +++ b/doc/user/project/merge_requests/img/squash_mr_message.png diff --git a/doc/user/project/merge_requests/img/wip_blocked_accept_button.png b/doc/user/project/merge_requests/img/wip_blocked_accept_button.png Binary files differindex b6d38d85165..ab2c8425b83 100644 --- a/doc/user/project/merge_requests/img/wip_blocked_accept_button.png +++ b/doc/user/project/merge_requests/img/wip_blocked_accept_button.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index f593046fa8b..2794cbc0f39 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -47,6 +47,7 @@ With **[GitLab Enterprise Edition][ee]**, you can also: - Analyze your dependencies for vulnerabilities with [Dependency Scanning](../../application_security/dependency_scanning/index.md) **(ULTIMATE)** - Analyze your Docker images for vulnerabilities with [Container Scanning](../../application_security/container_scanning/index.md) **(ULTIMATE)** - Determine the performance impact of changes with [Browser Performance Testing](#browser-performance-testing-premium) **(PREMIUM)** +- Specify merge order dependencies with [Cross-project Merge Request Dependencies](#cross-project-merge-request-dependencies-premium) **(PREMIUM)** ## Use cases @@ -285,6 +286,9 @@ as pushing changes: - Create a new merge request for the pushed branch. - Set the target of the merge request to a particular branch. - Set the merge request to merge when its pipeline succeeds. +- Set the merge request to remove the source branch when it's merged. +- Set the title of the merge request to a particular title. +- Set the description of the merge request to a particular description. ### Create a new merge request using git push options @@ -328,6 +332,49 @@ pipeline succeeds at the same time using a `-o` flag per push option: git push -o merge_request.create -o merge_request.merge_when_pipeline_succeeds ``` +### Set removing the source branch using git push options + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/64320) in GitLab 12.2. + +To set an existing merge request to remove the source branch when the +merge request is merged, the +`merge_request.remove_source_branch` push option can be used: + +```sh +git push -o merge_request.remove_source_branch +``` + +You can also use this push option in addition to the +`merge_request.create` push option. + +### Set merge request title using git push options + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/64320) in GitLab 12.2. + +To set the title of an existing merge request, use +the `merge_request.title` push option: + +```sh +git push -o merge_request.title="The title I want" +``` + +You can also use this push option in addition to the +`merge_request.create` push option. + +### Set merge request description using git push options + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/64320) in GitLab 12.2. + +To set the description of an existing merge request, use +the `merge_request.description` push option: + +```sh +git push -o merge_request.description="The description I want" +``` + +You can also use this push option in addition to the +`merge_request.create` push option. + ## Find the merge request that introduced a change > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/2383) in GitLab 10.5. @@ -365,6 +412,11 @@ have been marked as a **Work In Progress**. [Learn more about setting a merge request as "Work In Progress".](work_in_progress_merge_requests.md) +## Merge Requests for Confidential Issues + +Create [merge requests to resolve confidential issues](../issues/confidential_issues.md#merge-requests-for-confidential-issues) +for preventing leakage or early release of sentive data through regular merge requests. + ## Merge request approvals **(STARTER)** > Included in [GitLab Starter][products]. @@ -386,6 +438,17 @@ can show the Code Climate report right in the merge request widget area. [Read more about Code Quality reports.](code_quality.md) +## Metrics Reports **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9788) in [GitLab Premium][products] 11.10. +Requires GitLab Runner 11.10 and above. + +If you are using [GitLab CI][ci], you can configure your job to output custom +metrics and GitLab will display the Metrics Report on the merge request so +that it's fast and easy to identify changes to important metrics. + +[Read more about Metrics Report](../../../ci/metrics_reports.md). + ## Browser Performance Testing **(PREMIUM)** > Introduced in [GitLab Premium][products] 10.3. @@ -396,6 +459,21 @@ GitLab runs the [Sitespeed.io container][sitespeed-container] and displays the d [Read more about Browser Performance Testing.](browser_performance_testing.md) +## Cross-project Merge Request Dependencies **(PREMIUM)** + +> Introduced in [GitLab Premium][products] 12.2. + +A single logical change may be split across several merge requests, across +several projects. When this happens, the order in which MRs are merged is +important. + +GitLab allows you to specify that a merge request depends on other MRs. With +this relationship in place, the merge request cannot be merged until all of its +dependencies have also been merged, helping to maintain the consistency of a +single logical change. + +[Read more about cross-project merge request dependencies.](merge_request_dependencies.md) + ## Security reports **(ULTIMATE)** GitLab can scan and report any vulnerabilities found in your project. @@ -410,15 +488,6 @@ without having to check the entire job log. [Read more about JUnit test reports](../../../ci/junit_test_reports.md). -## Live preview with Review Apps - -If you configured [Review Apps](https://about.gitlab.com/features/review-apps/) for your project, -you can preview the changes submitted to a feature-branch through a merge request -in a per-branch basis. No need to checkout the branch, install and preview locally; -all your changes will be available to preview by anyone with the Review Apps link. - -[Read more about Review Apps.](../../../ci/review_apps/index.md) - ## Merge request diff file navigation When reviewing changes in the **Changes** tab the diff can be navigated using @@ -428,6 +497,15 @@ list.  +### Incrementally expand merge request diffs + +By default, the diff shows only the parts of a file which are changed. +To view more unchanged lines above or below a change click on the +**Expand up** or **Expand down** icons. You can also click on **Show all lines** +to expand the entire file. + + + ## Ignore whitespace changes in Merge Request diff view If you click the **Hide whitespace changes** button, you can see the diff diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md index 220795d6f15..5161b25de99 100644 --- a/doc/user/project/merge_requests/merge_request_approvals.md +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -44,7 +44,7 @@ To edit the merge request approvals: 1. Navigate to your project's **Settings > General** and expand **Merge request approvals**. -  +  1. Click **Edit**. 1. Search for users or groups that will be [eligible to approve](#eligible-approvers) @@ -54,7 +54,7 @@ To edit the merge request approvals: box. Note: the minimum can be 0. 1. Click **Update approvers**. -  +  The steps above are the minimum required to get approvals working in your merge requests, but there are a couple more options available that might be @@ -83,7 +83,7 @@ request approval rules: 1. Give the approval rule a name that describes the set of approvers selected. 1. Click **Add approvers** to submit the new rule. -  +  ## Multiple approval rules **(PREMIUM)** @@ -144,14 +144,17 @@ the following is possible: - If the required number of approvals has _not_ been yet met, they can approve it by clicking the displayed **Approve** button. -  + +  + - If the required number of approvals has already been met, they can still approve it by clicking the displayed **Approve additionally** button. -  + +  - **They have already approved this merge request**: They can remove their approval. -  +  NOTE: **Note:** The merge request author is only allowed to approve their own merge request @@ -159,7 +162,7 @@ if [**Prevent author approval**](#allowing-merge-request-authors-to-approve-thei For a given merge request, if the approval restrictions have been satisfied, the merge request is unblocked and can be merged. -Note, that meeting the required number of approvals is a necessary, but not +Note that meeting the required number of approvals is a necessary, but not sufficient condition for unblocking a merge request from being merged. There are other conditions that may block it, such as merge conflicts, [pending discussions](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved) @@ -203,7 +206,7 @@ First, you have to enable this option in the project's settings: 1. Tick the "Can override approvers and approvals required per merge request" checkbox -  +  1. Click **Save changes** @@ -226,12 +229,6 @@ The default approval settings can now be overridden when creating a in the **No. approvals required** box. 1. Click **Update approvers**. -There are however some restrictions: - -- The amount of required approvals, if changed, must be greater than the default - set at the project level. This ensures that you're not forced to adjust settings - when someone is unavailable for approval, yet the process is still enforced. - NOTE: **Note:** If you are contributing to a forked project, things are a little different. Read what happens when the @@ -239,14 +236,9 @@ Read what happens when the ## Overriding merge request approvals default settings **(PREMIUM)** -In GitLab Premium, when the approval rules are [set at the project level](#editing-approvals-premium), and -**Can override approvers and approvals required per merge request** is checked, there are a few more -restrictions (compared to [GitLab Starter](#overriding-the-merge-request-approvals-default-settings)): - -- Approval rules can be added to an MR with no restriction. -- For project sourced approval rules, editing and removing approvers is not allowed. -- The approvals required of all approval rules is configurable, but if a rule is backed by a project rule, then it is restricted - to the minimum approvals required set in the project's corresponding rule. +In GitLab Premium, when the approval rules are [set at the project level](#editing-approvals-premium), +and **Can override approvers and approvals required per merge request** is checked, +approval rules can be added to an MR with no restriction. ## Resetting approvals on push @@ -259,7 +251,7 @@ new commits are pushed to the source branch of the merge request: 1. Tick the "Remove all approvals in a merge request when new commits are pushed to its source branch" checkbox -  +  1. Click **Save changes** @@ -331,6 +323,16 @@ the dropdown) `approver` and select the user.  +## Security approvals in merge requests **(ULTIMATE)** + +> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing) 12.2. + +Merge Request Approvals can be configured to require approval from a member +of your security team when a vulnerability would be introduced by a merge request. + +For more information, see +[Security approvals in merge requests](../../application_security/index.md#security-approvals-in-merge-requests-ultimate). + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md new file mode 100644 index 00000000000..b30e24b2386 --- /dev/null +++ b/doc/user/project/merge_requests/merge_request_dependencies.md @@ -0,0 +1,142 @@ +--- +type: reference, concepts +--- + +# Cross-project Merge Request dependencies **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9688) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. + +Cross-project merge request dependencies allows a required order of merging +between merge requests in different projects to be expressed. If a +merge request "depends on" another, then it cannot be merged until its +dependency is itself merged. + +NOTE: **Note:** +Merge requests dependencies are a **PREMIUM** feature, but this restriction is +only enforced for the dependent merge request. A merge request in a **CORE** or +**STARTER** project can be a dependency of a **PREMIUM** merge request, but not +vice-versa. + +NOTE: **Note:** +A merge request can only depend on merge requests in a different project. Two +merge requests in the same project cannot depend on each other. + +## Use cases + +- Ensure changes to a library are merged before changes to a project that + imports the library. +- Prevent a documentation-only merge request from being merged before the merge request + implementing the feature to be documented. +- Require an merge request updating a permissions matrix to be merged before merging an + merge request from someone who hasn't yet been granted permissions. + +It is common for a single logical change to span several merge requests, spread +out across multiple projects, and the order in which they are merged can be +significant. + +For example, given a project `mycorp/awesome-project` that imports a library +at `myfriend/awesome-lib`, adding a feature in `awesome-project` may **also** +require changes to `awesome-lib`, and so necessitate two merge requests. Merging +the `awesome-project` merge request before the `awesome-lib` one would +break the `master`branch. + +The `awesome-project` merge request could be [marked as +WIP](work_in_progress_merge_requests.md), +and the reason for the WIP stated included in the comments. However, this +requires the state of the `awesome-lib` merge request to be manually +tracked, and doesn't scale well if the `awesome-project` merge request +depends on changes to **several** other projects. + +By making the `awesome-project` merge request depend on the +`awesome-lib` merge request instead, this relationship is +automatically tracked by GitLab, and the WIP state can be used to +communicate the readiness of the code in each individual merge request +instead. + +## Configuration + +To continue the above example, you can configure a dependency when creating the +new merge request in `awesome-project` (or by editing it, if it already exists). +The dependency needs to be configured on the **dependent** merge +request. There is a "Cross-project dependencies" section in the form: + + + +Anyone who can edit a merge request can change the list of dependencies. + +New dependencies can be added by reference, or by URL. To remove a dependency, +press the **X** by its reference. + +As dependencies are specified across projects, it's possible that someone else +has added a dependency for a merge request in a project you don't have access to. +These are shown as a simple count: + + + +If necessary, you can remove all the dependencies like this by pressing the +**X**, just as you would for a single, visible dependency. + +Once you're finished, press the **Save changes** button to submit the request, +or **Cancel** to return without making any changes. + +The list of configured dependencies, and the status of each one, is shown in the +merge request widget: + + + +Until all dependencies have, themselves, been merged, the **Merge** +button will be disabled for the dependent merge request. In +particular, note that **closed merge requests** still prevent their +dependents from being merged - it is impossible to automatically +determine whether the dependency expressed by a closed merge request +has been satisfied in some other way or not. + +If a merge request has been closed **and** the dependency is no longer relevant, +it must be removed as a dependency, following the instructions above, before +merge. + +## Limitations + +- API support: [gitlab-ee#12551](https://gitlab.com/gitlab-org/gitlab-ee/issues/12551) +- Dependencies are not preserved across project export/import: [gitlab-ee#12549](https://gitlab.com/gitlab-org/gitlab-ee/issues/12549) +- Complex merge order dependencies are not supported: [gitlab-ee#11393](https://gitlab.com/gitlab-org/gitlab-ee/issues/11393) + +The last item merits a little more explanation. Dependencies between merge +requests can be described as a graph of relationships. The simplest possible +graph has one merge request that depends upon another: + +```mermaid +graph LR; + myfriend/awesome-lib!10-->mycorp/awesome-project!100; +``` + +A more complex (and still supported) graph might have one merge request that +directly depends upon several others: + +```mermaid +graph LR; + myfriend/awesome-lib!10-->mycorp/awesome-project!100; + herfriend/another-lib!1-->mycorp/awesome-project!100; +``` + +Several different merge requests can also directly depend upon the +same merge request: + +```mermaid +graph LR; + herfriend/another-lib!1-->myfriend/awesome-lib!10; + herfriend/another-lib!1-->mycorp/awesome-project!100; +``` + +What is **not** supported is a "deep", or "nested" graph of dependencies, e.g.: + +```mermaid +graph LR; + herfriend/another-lib!1-->myfriend/awesome-lib!10; + myfriend/awesome-lib!10-->mycorp/awesome-project!100; +``` + +In this example, `myfriend/awesome-lib!10` depends on `herfriend/another-lib!1`, +and is itself a dependent of `mycorp/awesome-project!100`. This means that +`myfriend/awesome-lib!10` becomes an **indirect** dependency of +`mycorp/awesome-project!100`, which is not yet supported. |
