diff options
Diffstat (limited to 'doc/ci/merge_request_pipelines/index.md')
| -rw-r--r-- | doc/ci/merge_request_pipelines/index.md | 237 |
1 files changed, 4 insertions, 233 deletions
diff --git a/doc/ci/merge_request_pipelines/index.md b/doc/ci/merge_request_pipelines/index.md index 1866b40093a..c852800d0a9 100644 --- a/doc/ci/merge_request_pipelines/index.md +++ b/doc/ci/merge_request_pipelines/index.md @@ -1,237 +1,8 @@ --- -stage: Verify -group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: reference, index -last_update: 2019-07-03 +redirect_to: '../pipelines/merge_request_pipelines.md' --- -# Pipelines for Merge Requests +This document was moved to [another location](../pipelines/merge_request_pipelines.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/15310) in GitLab 11.6. - -In a [basic configuration](../pipelines/pipeline_architectures.md#basic-pipelines), GitLab runs a pipeline each time -changes are pushed to a branch. - -If you want the pipeline to run jobs **only** on commits to a branch that is associated with a merge request, -you can use *pipelines for merge requests*. - -In the UI, these pipelines are labeled as `detached`. Otherwise, these pipelines appear the same -as other pipelines. - -Pipelines for merge requests can run when you: - -- Create a new merge request. -- Commit changes to the source branch for the merge request. -- Select the **Run pipeline** button from the **Pipelines** tab in the merge request. - -Any user who has developer [permissions](../../user/permissions.md) -can run a pipeline for merge requests. - - - -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. - -## Prerequisites - -To enable pipelines for merge requests: - -- 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. - -## Configuring pipelines for merge requests - -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: - -### Use `rules` to run pipelines for merge requests - -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 - -If you want to continue using `only/except`, this is possible but please review the drawbacks -below. - -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` keyword, -so they don't run on merge requests. - -```yaml -build: - stage: build - script: ./build - only: - - main - -test: - stage: test - script: ./test - only: - - merge_requests - -deploy: - stage: deploy - script: ./deploy - only: - - main -``` - -#### Excluding certain jobs - -The behavior of the `only: [merge_requests]` keyword is such that _only_ jobs with -that keyword are run in the context of a merge request; no other jobs run. - -However, you can invert this behavior and have all of your jobs run _except_ -for one or two. - -Consider the following pipeline, with jobs `A`, `B`, and `C`. Imagine you want: - -- All pipelines to always run `A` and `B`. -- `C` to run only for merge requests. - -To achieve this, you can configure your `.gitlab-ci.yml` file as follows: - -```yaml -.only-default: &only-default - only: - - main - - merge_requests - - tags - -A: - <<: *only-default - script: - - ... - -B: - <<: *only-default - script: - - ... - -C: - script: - - ... - only: - - merge_requests -``` - -Therefore: - -- Since `A` and `B` are getting the `only:` rule to execute in all cases, they always run. -- Since `C` specifies that it should only run for merge requests, it doesn't run for any pipeline - except a merge request pipeline. - -This helps you avoid having to add the `only:` rule to all of your jobs to make -them always run. You can use this format to set up a Review App, helping to -save resources. - -#### Excluding certain branches - -Pipelines for merge requests require special treatment when -using [`only`/`except`](../yaml/README.md#only--except). Unlike ordinary -branch refs (for example `refs/heads/my-feature-branch`), merge request refs -use a special Git reference that looks like `refs/merge-requests/:iid/head`. Because -of this, the following configuration will **not** work as expected: - -```yaml -# Does not exclude a branch named "docs-my-fix"! -test: - only: [merge_requests] - except: [/^docs-/] -``` - -Instead, you can use the -[`$CI_COMMIT_REF_NAME` predefined environment -variable](../variables/predefined_variables.md) in -combination with -[`only:variables`](../yaml/README.md#onlyvariables--exceptvariables) to -accomplish this behavior: - -```yaml -test: - only: [merge_requests] - except: - variables: - - $CI_COMMIT_REF_NAME =~ /^docs-/ -``` - -## Pipelines for Merged Results **(PREMIUM)** - -Read the [documentation on Pipelines for Merged Results](pipelines_for_merged_results/index.md). - -### Merge Trains **(PREMIUM)** - -Read the [documentation on Merge Trains](pipelines_for_merged_results/merge_trains/index.md). - -## Run pipelines in the parent project for merge requests from a forked project **(PREMIUM)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217451) in GitLab 13.3. -> - [Moved](https://about.gitlab.com/blog/2021/01/26/new-gitlab-product-subscription-model/) to GitLab Premium in 13.9. - -By default, external contributors working from forks can't create pipelines in the -parent project. When a pipeline for merge requests is triggered by a merge request -coming from a fork: - -- It's created and runs in the fork (source) project, not the parent (target) project. -- It uses the fork project's CI/CD configuration and resources. - -If a pipeline runs in a fork, the **fork** icon appears for the pipeline in the merge request. - - - -Sometimes parent project members want the pipeline to run in the parent -project. This could be to ensure that the post-merge pipeline passes in the parent project. -For example, a fork project could try to use a corrupted runner that doesn't execute -test scripts properly, but reports a passed pipeline. Reviewers in the parent project -could mistakenly trust the merge request because it passed a faked pipeline. - -Parent project members with at least [Developer permissions](../../user/permissions.md) -can create pipelines in the parent project for merge requests -from a forked project. In the merge request, go to the **Pipelines** and click -**Run pipeline** button. - -WARNING: -Fork merge requests could contain malicious code that tries to steal secrets in the -parent project when the pipeline runs, even before merge. Reviewers must carefully -check the changes in the merge request before triggering the pipeline. GitLab shows -a warning that must be accepted before the pipeline can be triggered. - -## Additional predefined variables - -By using pipelines for merge requests, GitLab exposes additional predefined variables to the pipeline jobs. -Those variables contain information of the associated merge request, so that it's useful -to integrate your job with [GitLab Merge Request API](../../api/merge_requests.md). - -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 - -### Two pipelines created when pushing to a merge request - -If you are experiencing duplicated pipelines when using `rules`, take a look at -the [important differences between `rules` and `only`/`except`](../jobs/job_control.md#avoid-duplicate-pipelines), -which helps 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`). - -In [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/201845) and later, -you can add `workflow:rules` to [switch from branch pipelines to merge request pipelines](../yaml/README.md#switch-between-branch-pipelines-and-merge-request-pipelines) -after a merge request is open on the branch. - -### 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. +<!-- This redirect file can be deleted after 2021-09-29. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> |