summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMarcia Ramos <marcia@gitlab.com>2019-06-17 14:23:08 +0000
committerMarcia Ramos <marcia@gitlab.com>2019-06-17 14:23:08 +0000
commitc857db9df0ee9990695059759b5d73fc2e36e3d4 (patch)
treed5ea25bd8f225a0e03df3ef7dae154a9319dbe0f
parentcdc2926946917d78582d3935c2a772a890eb4063 (diff)
parent3099724d6799d0b6514112ab1c448b18b36cf515 (diff)
downloadgitlab-ce-c857db9df0ee9990695059759b5d73fc2e36e3d4.tar.gz
Merge branch 'docs-merge-trains' into 'master'
Docs for Merge Trains See merge request gitlab-org/gitlab-ce!29047
-rw-r--r--doc/ci/merge_request_pipelines/img/merge_train_cancel.pngbin0 -> 19577 bytes
-rw-r--r--doc/ci/merge_request_pipelines/img/merge_train_config.pngbin0 -> 24267 bytes
-rw-r--r--doc/ci/merge_request_pipelines/img/merge_train_start.pngbin0 -> 8365 bytes
-rw-r--r--doc/ci/merge_request_pipelines/img/merge_train_start_when_pipeline_succeeds.pngbin0 -> 10323 bytes
-rw-r--r--doc/ci/merge_request_pipelines/index.md73
5 files changed, 71 insertions, 2 deletions
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 00000000000..1561fdcc7a5
--- /dev/null
+++ b/doc/ci/merge_request_pipelines/img/merge_train_cancel.png
Binary files 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 00000000000..fb0af43556e
--- /dev/null
+++ b/doc/ci/merge_request_pipelines/img/merge_train_config.png
Binary files 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 00000000000..f20108157d2
--- /dev/null
+++ b/doc/ci/merge_request_pipelines/img/merge_train_start.png
Binary files 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 00000000000..62c2f2f5ff5
--- /dev/null
+++ b/doc/ci/merge_request_pipelines/img/merge_train_start_when_pipeline_succeeds.png
Binary files differ
diff --git a/doc/ci/merge_request_pipelines/index.md b/doc/ci/merge_request_pipelines/index.md
index fe2fc790505..d8c1cefc8df 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