diff options
author | Marcia Ramos <marcia@gitlab.com> | 2019-07-03 14:06:52 +0300 |
---|---|---|
committer | Achilleas Pipinellis <axil@gitlab.com> | 2019-07-03 14:06:52 +0300 |
commit | ff0438fc6f89db14f3732558e8ddeeaa831e547f (patch) | |
tree | 3ab01f57906db1be8b3812f8bb518f293daeab5d /doc/ci/merge_request_pipelines | |
parent | 792af55fd455a4b1eb3f63d582925c40ab2b141d (diff) |
Move images to their own dirs
- Move images to each corresponding img/ folder
Diffstat (limited to 'doc/ci/merge_request_pipelines')
9 files changed, 185 insertions, 128 deletions
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. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> 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 Binary files differindex 58d5581f628..58d5581f628 100644 --- 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 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 Binary files differindex 0a84e61d284..0a84e61d284 100644 --- 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 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). + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> 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 Binary files differindex 1561fdcc7a5..1561fdcc7a5 100644 --- 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 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 Binary files differindex fb0af43556e..fb0af43556e 100644 --- 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 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 Binary files differindex f20108157d2..f20108157d2 100644 --- 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 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 Binary files differindex 62c2f2f5ff5..62c2f2f5ff5 100644 --- 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 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) + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> |