Working with Merge Request Pipelines
1. Enabling Merge Request Pipelines
| Setting | Description | Default | Notes |
|---|---|---|---|
| only/except | Controls when pipelines run based on branch or tag names | Runs on all branches | Can be used to restrict MR pipelines to specific branches |
| rules | Defines conditions under which a job runs | None | Allows fine-grained control over pipeline execution |
| trigger | Triggers another pipeline from a job | None | Useful for multi-stage or cross-project pipelines |
Example: Enabling MR Pipelines with Rules
workflow:
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request"
when: always
- if: $CI_PIPELINE_SOURCE != "merge_request"
when: never
test:
script:
- echo "Running tests"
Note: Merge Request pipelines are enabled by default in GitLab CI/CD. You can customize their behavior using
rules and only/except keywords.
2. Using Merge Request Variables (CI_MERGE_REQUEST_*)
| Variable | Description | Example Value |
|---|---|---|
| CI_MERGE_REQUEST_ID | Unique ID of the merge request | 12345 |
| CI_MERGE_REQUEST_IID | Internal ID of the merge request | 12345 |
| CI_MERGE_REQUEST_PROJECT_ID | ID of the project containing the merge request | 67890 |
| CI_MERGE_REQUEST_PROJECT_URL | URL of the project containing the merge request | https://gitlab.example.com/group/project |
| CI_MERGE_REQUEST_SOURCE_BRANCH_NAME | Name of the source branch | feature/new-feature |
| CI_MERGE_REQUEST_TARGET_BRANCH_NAME | Name of the target branch | main |
| CI_MERGE_REQUEST_SOURCE_PROJECT_ID | ID of the project where the source branch is located | 67891 |
| CI_MERGE_REQUEST_SOURCE_PROJECT_URL | URL of the project where the source branch is located | https://gitlab.example.com/group/project-2 |
| CI_MERGE_REQUEST_TITLE | Title of the merge request | Implement new feature |
| CI_MERGE_REQUEST_DESCRIPTION | Description of the merge request | This MR implements a new feature... |
Example: Using Merge Request Variables in a Pipeline
script:
- echo "Merge Request ID: $CI_MERGE_REQUEST_ID"
- echo "Source Branch: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"
- echo "Target Branch: $CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
3. Running Only on MR
| Option | Values | Notes |
|---|---|---|
| only | merges |
Runs job only when a merge request is created or updated |
| except | branches |
Excludes jobs from running on branches (only runs on MRs) |
Example: Running job only on MRs
job_name:
only:
- merges
except:
- branches
script:
- echo "Running only on merge requests"
Note: The
merges keyword ensures that the job runs only when a merge request is active, not on regular branch pushes.
4. Using Merged Results Pipelines
Merged Results Pipelines in GitLab CI/CD allow you to run pipelines on the merged codebase rather than on individual branches. This ensures that your pipeline tests the actual code that will be merged into the target branch.
| Configuration | Description | Default |
|---|---|---|
| workflow.merge_pipelines | Enables or disables merged results pipelines | false |
| workflow.merge_pipelines_strategy | Strategy for merging pipelines. Options: default, fast_forward |
default |
Example: Enabling Merged Results Pipelines
workflow:
merge_pipelines: true
merge_pipelines_strategy: fast_forward
test:
script:
- echo "Running tests on merged code"
Note: Merged Results Pipelines require GitLab Runner 15.0 or higher.
Warning: When using merged results pipelines, ensure that your pipeline configuration does not rely on branch-specific variables or settings.
5. Implementing Merge Trains
| Property | Description | Default | Notes |
|---|---|---|---|
| merge_trains | Enables or disables merge trains for a project | false | Requires GitLab Premium or Ultimate |
| merge_trains_enabled | Alias for merge_trains |
false | Deprecated in GitLab 16.0 |
Example: Enabling Merge Trains
variables:
MERGE_TRAINS_ENABLED: "true"
workflow:
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request"
Note: Merge trains require a
workflow rule to be enabled for merge requests.
Key Features of Merge Trains
- Automatically merge multiple merge requests into a single commit
- Reduce merge conflicts by testing changes together
- Supports
merge_trainsconfiguration in project settings - Requires GitLab Premium or Ultimate for full features
Merge Trains vs Regular Merging
- Regular Merging: Each MR is merged individually, increasing chance of conflicts
- Merge Trains: All MRs in a train are tested together before merging
- Performance: Merge trains can reduce CI/CD pipeline runtime by batching tests
6. Using Coverage Comparison
Example: Setting up coverage comparison in a GitLab CI job
coverage:
script:
- npm run test
- coverage report --compare-to=main
artifacts:
reports:
coverage: coverage/lcov.info
| Property | Description | Values | Notes |
|---|---|---|---|
| coverage.report | Path to coverage report file | coverage/lcov.info |
Required for coverage comparison |
| coverage.compare-to | Branch or commit to compare coverage against | main, develop |
Defaults to main if not specified |
Note: Coverage comparison requires
artifacts to be configured with reports.coverage.
Warning: Coverage reports must be in
lcov format to support comparison.
How Coverage Comparison Works
- Coverage reports are generated during CI job execution
- GitLab compares the current report with a baseline (e.g.,
main) - Results are displayed in the Merge Request UI under Coverage
- Changes in coverage percentage are highlighted for review
7. Setting MR Pipeline Strategy
| Strategy | Description | Notes |
|---|---|---|
| always_run | Runs the pipeline even if no changes are detected in the merge request. | Useful for ensuring that tests or deployments run consistently regardless of code changes. |
| on_success | Runs the pipeline only if previous stages in the merge request pipeline have succeeded. | Default behavior for most GitLab CI/CD pipelines. |
| on_failure | Runs the pipeline only if previous stages in the merge request pipeline have failed. | Useful for debugging or running recovery tasks after a failure. |
Example: Configuring MR Pipeline Strategy
workflow:
strategy: on_success
test_job:
stage: test
script:
- echo "Running tests"
Note: The
workflow.strategy setting applies to the entire pipeline and affects how stages are executed in merge request pipelines.
8. Blocking MR on Pipeline Failure
| Setting | Description | Default | Notes |
|---|---|---|---|
| pipeline_triggers.block_merge_on_failure | Blocks merge requests from being merged if the pipeline fails | false | Can be overridden per project or group |
| merge_request_pipeline.block_merge_on_failure | Enables or disables blocking merge requests on pipeline failure | false | Available since GitLab 15.0 |
Example: Enabling Merge Request Pipeline Blocking
workflow:
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request"
when: always
variables:
BLOCK_MERGE_ON_FAILURE: "true"
variables:
BLOCK_MERGE_ON_FAILURE: "false"
Note: This setting can be configured at the project or group level in GitLab's UI under
Settings > CI/CD > Merge Request Pipelines.
Warning: If enabled, the merge request will not be allowed to be merged until all pipeline jobs pass successfully.
9. Running MR-Specific Jobs
| Property | Description | Values |
|---|---|---|
| only | Defines when a job runs | merge_requests |
| except | Excludes jobs from running in specific contexts | branches, tags |
| resource_group | Groups jobs to prevent concurrent execution | mr_jobs_group |
Example: Running MR-specific job
test_mr_job:
only:
- merge_requests
script:
- echo "Running tests for MR"
Note: Jobs defined with
only: merge_requests will not run on branches or tags.
Warning: Ensure that MR-specific jobs do not interfere with branch pipeline jobs.
10. Using MR Labels in Rules
| Label | Usage in Rules | Notes |
|---|---|---|
| merge_request_labels | merge_request_labels: ['bug', 'feature'] |
Matches pipelines when the MR has any of the specified labels |
| merge_request_labels: ['critical'] | rules:- if: $CI_MERGE_REQUEST_LABELS =~ /critical/ |
Use regex to match labels with patterns |
| merge_request_labels: ['hotfix'] | rules:- if: $CI_MERGE_REQUEST_LABELS =~ /hotfix/ |
Matches pipelines when the MR has the 'hotfix' label |
Example: Using MR Labels in Rules
deploy_to_staging:
stage: deploy
rules:
- if: $CI_MERGE_REQUEST_LABELS =~ /hotfix/
when: manual
- if: $CI_MERGE_REQUEST_LABELS =~ /feature/
when: on_success
script:
- echo "Deploying to staging"
Note: The
$CI_MERGE_REQUEST_LABELS variable contains a comma-separated list of labels.