10 KiB
type | last_update |
---|---|
reference, index | 2019-07-03 |
Pipelines for Merge Requests
Introduced in GitLab 11.6.
In a basic configuration, GitLab runs a pipeline each time 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
.
A few notes:
- Pipelines for merge requests are incompatible with CI/CD for external repositories.
- Since GitLab 11.10, pipelines for merge requests require GitLab Runner 11.9.
- If you use this feature with merge when pipeline succeeds, 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. 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
.
In this example, the pipeline always runs for all merge requests, as well as for all changes to the master branch:
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
build:
stage: build
script: ./build
test:
stage: test
script: ./test
deploy:
stage: deploy
script: ./deploy
Enable pipelines for merge requests for specific jobs
To enable pipelines for merge requests for specific jobs, you can use
rules
.
In the following example:
- The
build
job runs for all changes to themaster
branch, as well as for all merge requests. - The
test
job runs for all merge requests. - The
deploy
job runs for all changes to themaster
branch, but does not run for merge requests.
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
test:
stage: test
script: ./test
rules:
- if: $CI_MERGE_REQUEST_ID # Execute jobs in merge request context
deploy:
stage: deploy
script: ./deploy
rules:
- if: $CI_COMMIT_BRANCH == 'master' # Execute jobs when a new commit is pushed to master branch
Use only
or except
to run pipelines for merge requests
NOTE: Note:
The only
/ except
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.
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.
build:
stage: build
script: ./build
only:
- master
test:
stage: test
script: ./test
only:
- merge_requests
deploy:
stage: deploy
script: ./deploy
only:
- master
Excluding certain jobs
The behavior of the only: [merge_requests]
parameter is such that only jobs with
that parameter are run in the context of a merge request; no other jobs will be 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
andB
. C
to run only for merge requests.
To achieve this, you can configure your .gitlab-ci.yml
file as follows:
.only-default: &only-default
only:
- master
- merge_requests
- tags
A:
<<: *only-default
script:
- ...
B:
<<: *only-default
script:
- ...
C:
script:
- ...
only:
- merge_requests
Therefore:
- Since
A
andB
are getting theonly:
rule to execute in all cases, they will always run. - Since
C
specifies that it should only run for merge requests, it will not run for any pipeline except a merge request pipeline.
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
Pipelines for merge requests require special treatment when
using 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:
# 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 in
combination with
only:variables
to
accomplish this behavior:
test:
only: [merge_requests]
except:
variables:
- $CI_COMMIT_REF_NAME =~ /^docs-/
Pipelines for Merged Results (PREMIUM)
Read the documentation on Pipelines for Merged Results.
Merge Trains (PREMIUM)
Read the documentation on Merge Trains.
Important notes about merge requests from forked projects
Note that the current behavior is subject to change. In the usual contribution flow, external contributors follow the following steps:
- Fork a parent project.
- Create a merge request from the forked project that targets the
master
branch in the parent project. - A pipeline runs on the merge request.
- A maintainer from the parent project checks the pipeline result, and merge into a target branch if the latest pipeline has passed.
Currently, those pipelines are created in a forked project, not in the parent project. This means you cannot completely trust the pipeline result, because, technically, external contributors can disguise their pipeline results by tweaking their GitLab Runner in the forked project.
There are multiple reasons why GitLab doesn't allow those pipelines to be
created in the parent project, but one of the biggest reasons is security concern.
External users could steal secret variables from the parent project by modifying
.gitlab-ci.yml
, which could be some sort of credentials. This should not happen.
We're discussing a secure solution of running pipelines for merge requests that are submitted from forked projects, see the issue about the permission extension.
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.
You can find the list of available variables in the reference sheet.
The variable names begin with the CI_MERGE_REQUEST_
prefix.
Troubleshooting
Two pipelines created when pushing to a merge request
If two pipelines are created when you push a new change to a merge request, check your CI configuration file.
For example, with this .gitlab-ci.yml
configuration:
test:
script: ./test
rules:
- if: $CI_MERGE_REQUEST_ID # Include this job in pipelines for merge request
- if: $CI_COMMIT_BRANCH # Include this job in all branch pipelines
# Or, if you are using the `only:` keyword:
# only:
# - merge_requests
# - branches
Two pipelines are created when you push a commit to a branch that also has a pending merge request:
-
A merge request pipeline that runs for the changes in the merge request. In CI/CD > Pipelines, the merge request icon ({merge-request}) and the merge request ID are displayed. If you hover over the ID, the merge request name is displayed.
-
A "branch" pipeline that runs for the commit pushed to the branch. In CI/CD > Pipelines, the branch icon ({branch}) and branch name are displayed. This pipeline is created even if no merge request exists.
With the example configuration above, there is overlap between these two events. When you push a commit to a branch that also has an open merge request pending, both types of pipelines are created.
To fix this overlap, you must explicitly define which job should run for which purpose, for example:
test:
script: ./test
rules:
- if: $CI_MERGE_REQUEST_ID # Include this job in pipelines for merge request
- if: $CI_COMMIT_BRANCH == 'master' # Include this job in master branch pipelines
Similar rules:
should be added to all jobs to avoid any overlapping pipelines. Alternatively,
you can use the workflow:
parameter to add the same rules to all jobs globally.
Two pipelines created when pushing an invalid CI configuration file
Similar to above, 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.
In rare cases, duplicate pipelines are created.
See this issue for details.