diff --git a/doc/ci/merge_request_pipelines/img/merge_train_cancel.png b/doc/ci/merge_request_pipelines/img/merge_train_cancel.png new file mode 100644 index 0000000000000000000000000000000000000000..1561fdcc7a53cfd2f288e237fbf785339f7f2eda Binary files /dev/null and b/doc/ci/merge_request_pipelines/img/merge_train_cancel.png differ diff --git a/doc/ci/merge_request_pipelines/img/merge_train_config.png b/doc/ci/merge_request_pipelines/img/merge_train_config.png new file mode 100644 index 0000000000000000000000000000000000000000..fb0af43556e8c58cb4a6c5b14da04831f0145dd9 Binary files /dev/null and b/doc/ci/merge_request_pipelines/img/merge_train_config.png differ diff --git a/doc/ci/merge_request_pipelines/img/merge_train_start.png b/doc/ci/merge_request_pipelines/img/merge_train_start.png new file mode 100644 index 0000000000000000000000000000000000000000..f20108157d29ed79ebdf32b2798113ea019f1060 Binary files /dev/null and b/doc/ci/merge_request_pipelines/img/merge_train_start.png differ diff --git a/doc/ci/merge_request_pipelines/img/merge_train_start_when_pipeline_succeeds.png b/doc/ci/merge_request_pipelines/img/merge_train_start_when_pipeline_succeeds.png new file mode 100644 index 0000000000000000000000000000000000000000..62c2f2f5ff5442c839b639642b3b170c23d05cc9 Binary files /dev/null and b/doc/ci/merge_request_pipelines/img/merge_train_start_when_pipeline_succeeds.png differ diff --git a/doc/ci/merge_request_pipelines/index.md b/doc/ci/merge_request_pipelines/index.md index fe2fc7905054be4178be410df98d596bd9c37586..d8c1cefc8df0dae5c051249bc794807db371616f 100644 --- a/doc/ci/merge_request_pipelines/index.md +++ b/doc/ci/merge_request_pipelines/index.md @@ -74,7 +74,7 @@ when a merge request was created or updated. For example: ## Pipelines for Merged Results **[PREMIUM]** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7380) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10. -> This feature is disabled by default until we resolve issues with [contention handling](https://gitlab.com/gitlab-org/gitlab-ee/issues/9186), but [can be enabled manually](#enabling-pipelines-for-merged-results). +> This feature is disabled by default until we resolve issues with [contention handling](https://gitlab.com/gitlab-org/gitlab-ee/issues/11222), but [can be enabled manually](#enabling-pipelines-for-merged-results). It's possible for your source and target branches to diverge, which can result in the scenario that source branch's pipeline was green, the target's pipeline was green, @@ -118,10 +118,79 @@ otherwise pipelines for merged results won't run and your merge requests will be - This feature requires [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner) 11.9 or newer. - This feature requires [Gitaly](https://gitlab.com/gitlab-org/gitaly) 1.21.0 or newer. -- After the merge request pipeline succeeds, if the target branch has moved forward, the result of the pipeline is stale and must be retried. In busy repos, this can become a problem as it is highly probable that the target branch will have moved ahead. Improvements are [planned](https://gitlab.com/gitlab-org/gitlab-ee/issues/9186) for future versions of GitLab. - Forking/cross-repo workflows are not currently supported. To follow progress, see [#9713](https://gitlab.com/gitlab-org/gitlab-ee/issues/9713). - This feature is not available for [fast forward merges](../../user/project/merge_requests/fast_forward_merge.md) yet. To follow progress, see [#58226](https://gitlab.com/gitlab-org/gitlab-ce/issues/58226). +## Merge Trains **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9186) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.0. +> This feature is disabled by default until we resolve issues with [contention handling](https://gitlab.com/gitlab-org/gitlab-ee/issues/11222), but [can be enabled manually](#enabling-merge-trains). + +[Pipelines for merged results](#pipelines-for-merged-results-premium) introduces +running a build on the result of the merged code prior to merging, as a way to keep master green. +There's a scenario, however, for teams with a high number of changes in the target branch (typically master) where in many or even all cases, +by the time the merged code is validated another commit has made it to master, invalidating the merged result. +You'd need some kind of queuing, cancellation or retry mechanism for these scenarios +in order to ensure an orderly flow of changes into the target branch. + +Each MR that joins a merge train joins as the last item in the train, +just as it works in the current state. However, instead of queuing and waiting, +each item takes the completed state of the previous (pending) merge ref, adds its own changes, +and starts the pipeline immediately in parallel under the assumption that everything is going to pass. +In this way, if all the pipelines in the train merge successfully, no pipeline time is wasted either queuing or retrying. +If the button is subsequently pressed in a different MR, instead of creating a new pipeline for the target branch, +it creates a new pipeline targeting the merge result of the previous MR plus the target branch. +Pipelines invalidated through failures are immediately canceled and requeued. + +CAUTION: **Warning:** +At this moment, each merge train can generate a merge ref and run a pipeline **one at a time** due to a technical challenge. +We have [an issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/11222) to tackle this problem to make the pipelines for merged results run in parallel. + +### Enabling Merge Trains + +To enable merge trains at the project level: + +1. Visit your project's **Settings > General** and expand **Merge requests**. +1. Check **Allow merge trains**. +1. Click **Save changes** button. + +![Merge request pipeline config](img/merge_train_config.png) + +CAUTION: **Warning:** +This feature requires [Pipelines for merged results](#pipelines-for-merged-results-premium) to be **configured properly**. + +### How to add a merge request to a merge train + +To add a merge request to a merge train: + +1. Click "Start/Add merge train" button in a merge request + +![Start merge train](img/merge_train_start.png) + +### How to remove a merge request from a merge train + +1. Click "Remove from merge train" button in the merge request widget. + +![Cancel merge train](img/merge_train_cancel.png) + +### Tips: Start/Add to merge train when pipeline succeeds + +You can add a merge request to a merge train only when the latest pipeline in the +merge request finished. While the pipeline is running or pending, you cannot add +the merge request to a train because the current change of the merge request may +be broken thus it could affect the following merge requests. + +In this case, you can schedule to add the merge request to a merge train **when the latest +pipeline succeeds**. You can see the following button instead of the regular "Start/Add merge train" +button while the latest pipeline is running. + +![Add to merge train when pipeline succeeds](img/merge_train_start_when_pipeline_succeeds.png) + +### Merge Train's limitations + +- At this moment, each merge train can generate a merge ref and run a pipeline **one at a time** due to a technical challenge. + We have [an issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/11222) to tackle this problem to make the pipelines for merged results run in parallel. + ## Excluding certain jobs The behavior of the `only: merge_requests` parameter is such that _only_ jobs with