diff options
Diffstat (limited to 'doc/ci/merge_request_pipelines')
| -rw-r--r-- | doc/ci/merge_request_pipelines/img/merge_request_pipelines_doubled_MR_v12_09.png | bin | 0 -> 29650 bytes | |||
| -rw-r--r-- | doc/ci/merge_request_pipelines/img/merge_request_pipelines_doubled_branch_v12_09.png | bin | 0 -> 29680 bytes | |||
| -rw-r--r-- | doc/ci/merge_request_pipelines/index.md | 128 | ||||
| -rw-r--r-- | doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md | 17 | ||||
| -rw-r--r-- | doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md | 21 |
5 files changed, 68 insertions, 98 deletions
diff --git a/doc/ci/merge_request_pipelines/img/merge_request_pipelines_doubled_MR_v12_09.png b/doc/ci/merge_request_pipelines/img/merge_request_pipelines_doubled_MR_v12_09.png Binary files differnew file mode 100644 index 00000000000..3e4c72b9279 --- /dev/null +++ b/doc/ci/merge_request_pipelines/img/merge_request_pipelines_doubled_MR_v12_09.png diff --git a/doc/ci/merge_request_pipelines/img/merge_request_pipelines_doubled_branch_v12_09.png b/doc/ci/merge_request_pipelines/img/merge_request_pipelines_doubled_branch_v12_09.png Binary files differnew file mode 100644 index 00000000000..dd70c3f8c20 --- /dev/null +++ b/doc/ci/merge_request_pipelines/img/merge_request_pipelines_doubled_branch_v12_09.png diff --git a/doc/ci/merge_request_pipelines/index.md b/doc/ci/merge_request_pipelines/index.md index b57340347d2..a724bf416b6 100644 --- a/doc/ci/merge_request_pipelines/index.md +++ b/doc/ci/merge_request_pipelines/index.md @@ -13,93 +13,47 @@ changes are pushed to a branch. If you want the pipeline to run jobs **only** when merge requests are created or updated, you can use *pipelines for merge requests*. -In the UI, these pipelines are labeled as `detached`. +In the UI, these pipelines are labeled as `detached`. Otherwise, these pipelines appear the same +as other pipelines. - - -A few notes: - -- 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. -- 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. - -## Configuring pipelines for merge requests - -To configure pipelines for merge requests, configure your [CI/CD configuration file](../yaml/README.md). -There are a few different ways to do this. - -### Enable pipelines for merge requests for all jobs - -The recommended method for enabling pipelines for merge requests for all jobs in -a pipeline is to use [`workflow:rules`](../yaml/README.md#workflowrules). - -In this example, the pipeline always runs for all merge requests, as well as for all changes -to the master branch: - -```yaml -workflow: - rules: - - if: $CI_MERGE_REQUEST_ID # Execute jobs in merge request context - - if: $CI_COMMIT_BRANCH == 'master' # Execute jobs when a new commit is pushed to master branch +Any user who has developer [permissions](../../user/permissions.md) +can run a pipeline for merge requests. -build: - stage: build - script: ./build - -test: - stage: test - script: ./test + -deploy: - stage: deploy - script: ./deploy -``` +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. -### Enable pipelines for merge requests for specific jobs +## Prerequisites -To enable pipelines for merge requests for specific jobs, you can use -[`rules`](../yaml/README.md#rules). +To enable pipelines for merge requests: -In the following example: +- You must have maintainer [permissions](../../user/permissions.md). +- Your repository must be a GitLab repository, not an + [external repository](../ci_cd_for_external_repos/index.md). +- [In GitLab 11.10 and later](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/25504), + you must be using GitLab Runner 11.9. -- The `build` job runs for all changes to the `master` branch, as well as for all merge requests. -- The `test` job runs for all merge requests. -- The `deploy` job runs for all changes to the `master` branch, but does *not* run - for merge requests. +## Configuring pipelines for merge requests -```yaml -build: - stage: build - script: ./build - rules: - - if: $CI_COMMIT_BRANCH == 'master' # Execute jobs when a new commit is pushed to master branch - - if: $CI_MERGE_REQUEST_ID # Execute jobs in merge request context +To configure pipelines for merge requests you need to configure your [CI/CD configuration file](../yaml/README.md). +There are a few different ways to do this: -test: - stage: test - script: ./test - rules: - - if: $CI_MERGE_REQUEST_ID # Execute jobs in merge request context +### Use `rules` to run pipelines for merge requests -deploy: - stage: deploy - script: ./deploy - rules: - - if: $CI_COMMIT_BRANCH == 'master' # Execute jobs when a new commit is pushed to master branch -``` +When using `rules`, which is the preferred method, we recommend starting with one +of the [`workflow:rules` templates](../yaml/README.md#workflowrules-templates) to ensure +your basic configuration is correct. Instructions on how to do this, as well as how +to customize, are available at that link. ### Use `only` or `except` to run pipelines for merge requests -NOTE: **Note**: -The [`only` / `except`](../yaml/README.md#onlyexcept-basic) keywords are going to be deprecated -and you should not use them. - -To enable pipelines for merge requests, you can use `only / except`. When you use this method, -you have to specify `only: - merge_requests` for each job. +If you want to continue using `only/except`, this is possible but please review the drawbacks +below. -In this example, the pipeline contains a `test` job that is configured to run on merge requests. +When you use this method, you have to specify `only: - merge_requests` for each job. In this +example, the pipeline contains a `test` job that is configured to run on merge requests. The `build` and `deploy` jobs don't have the `only: - merge_requests` parameter, so they will not run on merge requests. @@ -245,14 +199,24 @@ 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 +## Troubleshooting + +### Two pipelines created when pushing to a merge request + +If you are experiencing duplicated pipelines when using `rules`, take a look at +the [key details when using `rules`](../yaml/README.md#key-details-when-using-rules), +which will help you get your starting configuration correct. + +If you are seeing two pipelines when using `only/except`, please see the caveats +related to using `only/except` above (or, consider moving to `rules`). + +### Two pipelines created when pushing an invalid CI configuration file + +Pushing to a branch with an invalid CI configuration file can trigger +the creation of two types of failed pipelines. One pipeline is a failed merge request +pipeline, and the other is a failed branch pipeline, but both are caused by the same +invalid configuration. -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. +In rare cases, duplicate pipelines are created. -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. --> +See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/201845) for details. 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 fb5c7830ac2..c35a5d0a07e 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 @@ -34,14 +34,18 @@ 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 +Any user who has developer [permissions](../../../user/permissions.md) can run a +pipeline for merged results. -Pipelines for merged results have the following requirements and limitations: +## Prerequisites -- Pipelines for merged results require [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner) 11.9 or newer. -- Forking/cross-repo workflows are not currently supported. To follow progress, +To enable pipelines for merge results: + +- You must have maintainer [permissions](../../../user/permissions.md). +- You must be using [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner) 11.9 or later. +- You must not be forking or using cross-repo workflows. To follow progress, see [#11934](https://gitlab.com/gitlab-org/gitlab/issues/11934). -- This feature is not available for +- You must not be using [fast forward merges](../../../user/project/merge_requests/fast_forward_merge.md) yet. To follow progress, see [#58226](https://gitlab.com/gitlab-org/gitlab/-/issues/26996). @@ -93,7 +97,6 @@ canceled. Can be caused by some disabled feature flags. Please make sure that the following feature flags are enabled on your GitLab instance: -- `:ci_use_merge_request_ref` - `:merge_ref_auto_sync` To check and set these feature flag values, please ask an administrator to: @@ -107,14 +110,12 @@ To check and set these feature flag values, please ask an administrator to: 1. Check if the flags are enabled or not: ```ruby - Feature.enabled?(:ci_use_merge_request_ref) Feature.enabled?(:merge_ref_auto_sync) ``` 1. If needed, enable the feature flags: ```ruby - Feature.enable(:ci_use_merge_request_ref) Feature.enable(:merge_ref_auto_sync) ``` 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 641192afea1..d921b75aa44 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 @@ -30,6 +30,14 @@ If the pipeline for the merge request at the front of the train completes succes the changes are merged into the target branch, and the other pipelines continue to run. +To add a merge request to a merge train, you need [permissions](../../../../user/permissions.md) to push to the target branch. + +NOTE: **Note:** +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 +will be queued until a slot in the merge train is free. There is no limit to the +number of merge requests that can be queued. + ## Merge train example Three merge requests (`A`, `B` and `C`) are added to a merge train in order, which @@ -55,16 +63,13 @@ Watch this video for a demonstration on [how parallel execution of Merge Trains can prevent commits from breaking the default branch](https://www.youtube.com/watch?v=D4qCqXgZkHQ). -## Requirements and limitations +## Prerequisites -Merge trains have the following requirements and limitations: +To enable merge trains: -- Merge trains require [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner) 11.9 or newer. -- GitLab 12.0 and later requires [Redis](https://redis.io/) 3.2 or higher. -- 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 - will be queued until a slot in the merge train is free. There is no limit to the - number of merge requests that can be queued. +- You must have maintainer [permissions](../../../../user/permissions.md). +- You must be using [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner) 11.9 or later. +- In GitLab 12.0 and later, you need [Redis](https://redis.io/) 3.2 or later. ## Enable merge trains |
