diff --git a/doc/ci/README.md b/doc/ci/README.md index da864a0b3cc..d851a56ee0e 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -81,6 +81,7 @@ GitLab CI/CD supports numerous configuration options: | [Git submodules for CI/CD](git_submodules.md) | Configure jobs for using Git submodules.| | [SSH keys for CI/CD](ssh_keys/README.md) | Using SSH keys in your CI pipelines. | | [Pipelines triggers](triggers/README.md) | Trigger pipelines through the API. | +| [Pipelines for Merge Requests](merge_request_pipelines/index.md) | Design a pipeline structure for running a pipeline in merge requests. | | [Integrate with Kubernetes clusters](../user/project/clusters/index.md) | Connect your project to Google Kubernetes Engine (GKE) or an existing Kubernetes cluster. | | [GitLab Runner](https://docs.gitlab.com/runner/) | Configure your own GitLab Runners to execute your scripts. | | [Optimize GitLab and Runner for large repositories](large_repositories/index.md) | Recommended strategies for handling large repos. | diff --git a/doc/ci/merge_request_pipelines/index.md b/doc/ci/merge_request_pipelines/index.md index c3dbcf6a19f..e70ae0bd154 100644 --- a/doc/ci/merge_request_pipelines/index.md +++ b/doc/ci/merge_request_pipelines/index.md @@ -1,8 +1,9 @@ --- -type: reference +type: reference, index +last_update: 2019-07-03 --- -# Pipelines for merge requests +# Pipelines for Merge Requests > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/15310) in GitLab 11.6. @@ -75,135 +76,13 @@ when a merge request was created or updated. For example: ![Merge request page](img/merge_request.png) -## Pipelines for merged results **[PREMIUM]** +## 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/11222), but [can be enabled manually](#enabling-pipelines-for-merged-results). +Read the [documentation on Pipelines for Merged Results](pipelines_for_merged_results/index.md). -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, -but the combined output fails. +### Merge Trains **[PREMIUM]** -By having your merge request pipeline automatically -create a new ref that contains the merge result of the source and target branch -(then running a pipeline on that ref), we can better test that the combined result -is also valid. - -GitLab can run pipelines for merge requests -on this merged result. That is, where the source and target branches are combined into a -new ref and a pipeline for this ref validates the result prior to merging. - -![Merge request pipeline as the head pipeline](img/merge_request_pipeline.png) - -There are some cases where creating a combined ref is not possible or not wanted. -For example, a source branch that has conflicts with the target branch -or a merge request that is still in WIP status. In this case, the merge request pipeline falls back to a "detached" state -and runs on the source branch ref as if it was a regular pipeline. - -The detached state serves to warn you that you are working in a situation -subjected to merge problems, and helps to highlight that you should -get out of WIP status or resolve merge conflicts as soon as possible. - -### Requirements and limitations - -Pipelines for merged results require: - -- [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner) 11.9 or newer. -- [Gitaly](https://gitlab.com/gitlab-org/gitaly) 1.21.0 or newer. - -In addition, pipelines for merged results have the following limitations: - -- 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). - -### Enabling Pipelines for merged results - -To enable pipelines on merged results at the project level: - -1. Visit your project's **Settings > General** and expand **Merge requests**. -1. Check **Merge pipelines will try to validate the post-merge result prior to merging**. -1. Click **Save changes** button. - -![Merge request pipeline config](img/merge_request_pipeline_config.png) - -CAUTION: **Warning:** -Make sure your `gitlab-ci.yml` file is [configured properly for pipelines for merge requests](#configuring-pipelines-for-merge-requests), -otherwise pipelines for merged results won't run and your merge requests will be stuck in an unresolved state. - -## 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, 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. - -### Requirements and limitations - -Merge trains have the following requirements and limitations: - -- This feature requires that - [pipelines for merged results](#pipelines-for-merged-results-premium) are - **configured properly**. -- Each merge train can generate a merge ref and run a pipeline **one at a time**. - We plan to make the pipelines for merged results - [run in parallel](https://gitlab.com/gitlab-org/gitlab-ee/issues/11222) in a - future release. - -### 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) - -### 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) +Read the [documentation on Merge Trains](pipelines_for_merged_results/merge_trains/index.md). ## Excluding certain jobs @@ -289,3 +168,15 @@ to integrate your job with [GitLab Merge Request API](../../api/merge_requests.m You can find the list of available variables in [the reference sheet](../variables/predefined_variables.md). The variable names begin with the `CI_MERGE_REQUEST_` prefix. + + diff --git a/doc/ci/merge_request_pipelines/img/merge_request_pipeline.png b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merge_request_pipeline.png similarity index 100% rename from doc/ci/merge_request_pipelines/img/merge_request_pipeline.png rename to doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merge_request_pipeline.png diff --git a/doc/ci/merge_request_pipelines/img/merge_request_pipeline_config.png b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merge_request_pipeline_config.png similarity index 100% rename from doc/ci/merge_request_pipelines/img/merge_request_pipeline_config.png rename to doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merge_request_pipeline_config.png diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md new file mode 100644 index 00000000000..3c5088089fa --- /dev/null +++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md @@ -0,0 +1,78 @@ +--- +type: reference +last_update: 2019-07-03 +--- + +# 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/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, +but the combined output fails. + +By having your merge request pipeline automatically +create a new ref that contains the merge result of the source and target branch +(then running a pipeline on that ref), we can better test that the combined result +is also valid. + +GitLab can run pipelines for merge requests +on this merged result. That is, where the source and target branches are combined into a +new ref and a pipeline for this ref validates the result prior to merging. + +![Merge request pipeline as the head pipeline](img/merge_request_pipeline.png) + +There are some cases where creating a combined ref is not possible or not wanted. +For example, a source branch that has conflicts with the target branch +or a merge request that is still in WIP status. In this case, the merge request pipeline falls back to a "detached" state +and runs on the source branch ref as if it was a regular pipeline. + +The detached state serves to warn you that you are working in a situation +subjected to merge problems, and helps to highlight that you should +get out of WIP status or resolve merge conflicts as soon as possible. + +## Requirements and limitations + +Pipelines for merged results require: + +- [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner) 11.9 or newer. +- [Gitaly](https://gitlab.com/gitlab-org/gitaly) 1.21.0 or newer. + +In addition, pipelines for merged results have the following limitations: + +- 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). + +## Enabling Pipelines for Merged Results + +To enable pipelines on merged results at the project level: + +1. Visit your project's **Settings > General** and expand **Merge requests**. +1. Check **Merge pipelines will try to validate the post-merge result prior to merging**. +1. Click **Save changes** button. + +![Merge request pipeline config](img/merge_request_pipeline_config.png) + +CAUTION: **Warning:** +Make sure your `gitlab-ci.yml` file is [configured properly for pipelines for merge requests](../index.md#configuring-pipelines-for-merge-requests), +otherwise pipelines for merged results won't run and your merge requests will be stuck in an unresolved state. + +## Merge Trains **[PREMIUM]** + +Read the [documentation on Merge Trains](merge_trains/index.md). + + diff --git a/doc/ci/merge_request_pipelines/img/merge_train_cancel.png b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_cancel_v12_0.png similarity index 100% rename from doc/ci/merge_request_pipelines/img/merge_train_cancel.png rename to doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_cancel_v12_0.png diff --git a/doc/ci/merge_request_pipelines/img/merge_train_config.png b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_config_v12_0.png similarity index 100% rename from doc/ci/merge_request_pipelines/img/merge_train_config.png rename to doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_config_v12_0.png diff --git a/doc/ci/merge_request_pipelines/img/merge_train_start.png b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_start_v12_0.png similarity index 100% rename from doc/ci/merge_request_pipelines/img/merge_train_start.png rename to doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_start_v12_0.png diff --git a/doc/ci/merge_request_pipelines/img/merge_train_start_when_pipeline_succeeds.png b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_start_when_pipeline_succeeds_v12_0.png similarity index 100% rename from doc/ci/merge_request_pipelines/img/merge_train_start_when_pipeline_succeeds.png rename to doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_start_when_pipeline_succeeds_v12_0.png diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md new file mode 100644 index 00000000000..c5ff6f9ebed --- /dev/null +++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md @@ -0,0 +1,88 @@ +--- +type: reference +last_update: 2019-07-03 +--- + +# 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, but [can be enabled manually](#enabling-merge-trains). + +[Pipelines for merged results](../index.md#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. + +## Requirements and limitations + +Merge trains have the following requirements and limitations: + +- This feature requires that + [pipelines for merged results](../index.md#pipelines-for-merged-results-premium) are + **configured properly**. +- Each merge train can generate a merge ref and run a pipeline **one at a time**. + We plan to make the pipelines for merged results + [run in parallel](https://gitlab.com/gitlab-org/gitlab-ee/issues/11222) in a + future release. + +## 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_v12_0.png) + +## 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_v12_0.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_v12_0.png) + +## 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_v12_0.png) + +