1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
|
---
type: reference, concepts
---
# Blocking merge requests **(PREMIUM)**
> Introduced in GitLab Premium 12.2
Blocking merge requests allow dependencies between MRs to be expressed. If a
merge request is blocked by another MR, it cannot be merged until that blocking
MR is itself merged.
NOTE: **Note:**
Blocking merge requests are a **PREMIUM** feature, but this restriction is only
enforced for the blocked merge request. A merge request in a **CORE** or
**STARTER** project can block a **PREMIUM** merge request, but not vice-versa.
## 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 MR
implementing the feature to be documented
* Require an MR updating a permissions matrix to be merged before merging an
MR from someone who hasn't yet been granted permissions
It is common for a single logical change to span several merge requests. These
MRs may all be in a single project, or they may be 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` MR before the `awesome-lib` one would break the `master`
branch.
The `awesome-project` MR 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` MR to be manually tracked, and doesn't
scale well if the `awesome-project` MR depends on changes to **several** other
projects.
By marking the `awesome-project` MR as blocked on the `awesome-lib` MR instead,
the status of the dependency is automatically tracked by GitLab, and the WIP
state can be used to communicate the readiness of the code in each individual
MR instead.
## Configuration
To continue the above example, you can configure a block when creating the
new MR in `awesome-project` (or by editing it, if it already exists). The block
needs to be configured on the MR that will be **blocked**, rather than on the
**blocking** MR. There is a "Blocking merge requests" section in the form:
Anyone who can edit a merge request can change the list of blocking merge
requests.
New blocks can be added by reference, by URL, or by using autcompletion. To
remove a block, press the "X" by its reference.
As blocks can be specified across projects, it's possible that someone else has
added a block 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 blocks like this by pressing the "X", just
as you would for a single, visible block.
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 blocks, and the status of each one, is shown in the merge
request widget:
Until all blocking merge requests have, themselves, been merged, the "Merge"
button will be disabled. In particular, note that **closed** merge requests
still block their dependents - it is impossible to automatically determine if
merge requests that were blocked by that MR when it was open, are still blocked
when it is closed.
If a merge request has been closed **and** the block is no longer relevant, it
must be removed as a blocking MR, following the instructions above, before
merge.
## Limitations
* API support: [gitlab-ee#12551](https://gitlab.com/gitlab-org/gitlab-ee/issues/12551)
* Blocking relationships 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. Blocking merge requests can be
described as a graph of dependencies. The simplest possible graph has one
merge request blocking another:
```mermaid
graph LR;
myfriend/awesome-lib!10-->mycorp/awesome-project!100;
```
A more complex (and still supported) graph might have several MRs blocking
another from being merged:
```mermaid
graph LR;
myfriend/awesome-lib!10-->mycorp/awesome-project!100;
herfriend/another-lib!1-->mycorp/awesome-project!100;
```
We also support one MR blocking several others from being merged:
```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` would be blocked from being merged by
`herfriend/another-lib!1`, and would also block `mycorp/awesome-project!100`
from being merged. This is **not** yet supported.
|
