diff options
Diffstat (limited to 'doc/ci')
| -rw-r--r-- | doc/ci/caching/index.md | 2 | ||||
| -rw-r--r-- | doc/ci/jenkins/index.md | 2 | ||||
| -rw-r--r-- | doc/ci/merge_request_pipelines/index.md | 55 | ||||
| -rw-r--r-- | doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merged_result_pipeline_v12_3.png | bin | 7734 -> 0 bytes | |||
| -rw-r--r-- | doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md | 51 | ||||
| -rw-r--r-- | doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md | 62 |
6 files changed, 92 insertions, 80 deletions
diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index 4e2e61cfadf..c2d206dde54 100644 --- a/doc/ci/caching/index.md +++ b/doc/ci/caching/index.md @@ -265,7 +265,7 @@ test: Assuming your project is using [pip](https://pip.pypa.io/en/stable/) to install the Python dependencies, the following example defines `cache` globally so that -all jobs inherit it. Python libraries are installed in a virtualenv under `venv/`, +all jobs inherit it. Python libraries are installed in a virtual environment under `venv/`, pip's cache is defined under `.cache/pip/` and both are cached per-branch: ```yaml diff --git a/doc/ci/jenkins/index.md b/doc/ci/jenkins/index.md index ea4ecbcca7f..37d6921c0a5 100644 --- a/doc/ci/jenkins/index.md +++ b/doc/ci/jenkins/index.md @@ -185,7 +185,7 @@ In self-managed GitLab instances, you can build an [Instance Template Repository Development teams across the whole organization can select templates from a dropdown menu. A group administrator is able to set a group to use as the source for the [custom project templates](../../user/admin_area/custom_project_templates.md), which can -be used by all projects in the group. An instance adminsitrator can set a group as +be used by all projects in the group. An instance administrator can set a group as the source for [instance project templates](../../user/group/custom_project_templates.md), which can be used by projects in that instance. diff --git a/doc/ci/merge_request_pipelines/index.md b/doc/ci/merge_request_pipelines/index.md index d1749924ad3..4e02955bcea 100644 --- a/doc/ci/merge_request_pipelines/index.md +++ b/doc/ci/merge_request_pipelines/index.md @@ -7,40 +7,32 @@ last_update: 2019-07-03 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/15310) in GitLab 11.6. -Usually, when you create a new merge request, a pipeline runs with the -new change and checks if it's qualified to be merged into a target branch. This -pipeline should contain only necessary jobs for validating the new changes. -For example, unit tests, lint checks, and [Review Apps](../review_apps/index.md) -are often used in this cycle. +In a [basic configuration](../pipelines/pipeline_architectures.md), GitLab runs a pipeline each time +changes are pushed to a branch. The settings in the [`.gitlab-ci.yml`](../yaml/README.md) +file, including `rules`, `only`, and `except`, determine which jobs are added to a pipeline. -With pipelines for merge requests, you can design a specific pipeline structure -for when you are running a pipeline in a merge request. This -could be either adding or removing steps in the pipeline, to make sure that -your pipelines are as efficient as possible. +If you want the pipeline to run jobs **only** when merge requests are created or updated, +you can use *pipelines for merge requests*. -## Requirements and limitations +In the UI, these pipelines are labeled as `detached`. -Pipelines for merge requests have the following requirements and limitations: + + +A few notes: -- As of GitLab 11.10, pipelines for merge requests require GitLab Runner 11.9 - or higher due to the - [recent refspecs changes](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/25504). - Pipelines for merge requests are incompatible with [CI/CD for external repositories](../ci_cd_for_external_repos/index.md). +- [Since GitLab 11.10](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/25504), pipelines for merge requests require GitLab Runner 11.9. ## Configuring pipelines for merge requests To configure pipelines for merge requests, add the `only: [merge_requests]` parameter to -the jobs that you want to run only for merge requests. - -Then, when developers create or update merge requests, a pipeline runs -every time a commit is pushed to GitLab. +your `.gitlab-ci.yml` file. -NOTE: **Note**: -If you use this feature with [merge when pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md), -pipelines for merge requests take precedence over the other regular pipelines. +In this example, the pipeline contains a `test` job that is configured to run on merge requests. -For example, consider the following [`.gitlab-ci.yml`](../yaml/README.md): +The `build` and `deploy` jobs don't have the `only: - merge_requests` parameter, +so they will not run on merge requests. ```yaml build: @@ -62,19 +54,14 @@ deploy: - master ``` -After the merge request is updated with new commits: +Whenever a merge request is updated with new commits: - GitLab detects that changes have occurred and creates a new pipeline for the merge request. - The pipeline fetches the latest code from the source branch and run tests against it. -In the above example, the pipeline contains only a `test` job. -Since the `build` and `deploy` jobs don't have the `only: [merge_requests]` parameter, -they will not run in the merge request. - -Pipelines tagged with the **detached** badge indicate that they were triggered -when a merge request was created or updated. For example: - - +NOTE: **Note**: +If you use this feature with [merge when pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md), +pipelines for merge requests take precedence over the other regular pipelines. ## Pipelines for Merged Results **(PREMIUM)** @@ -129,10 +116,8 @@ Therefore: - Since `C` specifies that it should only run for merge requests, it will not run for any pipeline except a merge request pipeline. -As you can see, this will help you avoid a lot of boilerplate where you'd need -to add that `only:` rule to all of your jobs in order to make them always run. You -can use this for scenarios like having only pipelines with merge requests get a -Review App set up, helping to save resources. +This helps you avoid having to add the `only:` rule to all of your jobs +in order to make them always run. You can use this format to set up a Review App, helping to save resources. ## Excluding certain branches diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merged_result_pipeline_v12_3.png b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merged_result_pipeline_v12_3.png Binary files differdeleted file mode 100644 index 8da2970ab5a..00000000000 --- a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merged_result_pipeline_v12_3.png +++ /dev/null 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 index ca980bb58c3..bab03f11aa8 100644 --- a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md +++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md @@ -7,31 +7,32 @@ last_update: 2019-07-03 > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/7380) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10. -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. - - - -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, -GitLab doesn't create a merge commit and the pipeline runs on source branch, instead, -which is a default behavior of [Pipelines for merge requests](../index.md) - i.e. `detached` label is shown to the pipelines. - -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. +When you submit a merge request, you are requesting to merge changes from a +source branch into a target branch. By default, the CI pipeline runs jobs +against the source branch. + +With *pipelines for merged results*, the pipeline runs as if the changes from +the source branch have already been merged into the target branch. + +If the pipeline fails due to a problem in the target branch, you can wait until the +target is fixed and re-run the pipeline. +This new pipeline will run as if the source is merged with the updated target, and you +will not need to rebase. + +The pipeline does not automatically run when the target branch changes. Only changes +to the source branch trigger a new pipeline. If a long time has passed since the last successful +pipeline, you may want to re-run it before merge, to ensure that the source changes +can still be successfully merged into the target. + +When the merge request can't be merged, the pipeline runs against the source branch only. For example, when: + +- The target branch has changes that conflict with the changes in the source branch. +- The merge request is a + [work in progress](../../../user/project/merge_requests/work_in_progress_merge_requests.md). + +In these cases, the pipeline runs as a [pipeline for merge requests](../index.md) +and is labeled as `detached`. If these cases no longer exist, new pipelines will +again run against the merged results. ## Requirements and limitations 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 index 54eccc2919c..1859328247b 100644 --- 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 @@ -8,31 +8,57 @@ last_update: 2019-07-03 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9186) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.0. > - [Squash and merge](../../../../user/project/merge_requests/squash_and_merge.md) support [introduced](https://gitlab.com/gitlab-org/gitlab/issues/13001) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.6. -[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. +When [pipelines for merged results](../index.md#pipelines-for-merged-results-premium) are +enabled, the pipeline jobs run as if the changes from your source branch have already +been merged into the target branch. -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. +However, the target branch may be changing rapidly. When you're ready to merge, +if you haven't run the pipeline in a while, the target branch may have already changed. +Merging now could introduce breaking changes. -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. +*Merge trains* can prevent this from happening. A merge train is a queued list of merge +requests, each waiting to be merged into the target branch. -This means that 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. +Each merge request on the train runs the merged results pipeline immediately before its +changes are merged into the target branch. If the pipeline fails, the breaking changes are +not merged, and the target branch is unaffected. + +Many merge requests can be added to the train. Each is trying to merge into the target branch. +Each request runs its own merged results pipeline, which includes the changes from +all of the other merge requests in *front* of it on the train. All the pipelines run +in parallel, to save time. + +If the pipeline for the merge request at the front of the train completes successfully, +the changes are merged into the target branch, and the other pipelines will continue to +run. + +If one of the pipelines fails, it is removed from the train, and all pipelines behind +it restart, but without the changes that were removed. + +Three merge requests (`A`, `B` and `C`) are added to a merge train in order, which +creates three merged results pipelines that run in parallel: + +1. The first pipeline runs on the changes from `A` combined with the target branch. +1. The second pipeline runs on the changes from `A` and `B` combined with the target branch. +1. The third pipeline runs on the changes from `A`, `B`, and `C` combined with the target branch. + +If the pipeline for `B` fails, it is removed from the train. The pipeline for +`C` restarts with the `A` and `C` changes, but without the `B` changes. + +If `A` then completes successfully, it merges into the target branch, and `C` continues +to run. If more merge requests are added to the train, they will now include the `A` +changes that are included in the target branch, and the `C` changes that are from +the merge request already in the train. + +Learn more about +[how merge trains keep your master green](https://about.gitlab.com/blog/2020/01/30/all-aboard-merge-trains/). ## Requirements and limitations Merge trains have the following requirements and limitations: -- GitLab 12.0 and later requires [Redis](https://redis.io/) 3.2 or higher to run Merge Trains. -- This feature requires that - [pipelines for merged results](../index.md#pipelines-for-merged-results-premium) are +- GitLab 12.0 and later requires [Redis](https://redis.io/) 3.2 or higher. +- [Pipelines for merged results](../index.md#pipelines-for-merged-results-premium) must be **configured properly**. - Each merge train can run a maximum of **twenty** pipelines in parallel. If more than twenty merge requests are added to the merge train, the merge requests @@ -70,7 +96,7 @@ current position will be displayed under the pipeline widget: ## 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 +merge request is 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. |
