GitLab CI/CD: Architecting, Deploying, and Optimizing Pipelines

Architecture Core Concepts

Raise a Merge Request amp Use rules at Job level

In this lesson, you’ll learn how to restrict a GitLab CI/CD job so that it only runs for merge request events. We will explore predefined pipeline variables and apply the rules keyword at the job level to include or exclude jobs based on CI_PIPELINE_SOURCE.

1. Define Jobs in .gitlab-ci.yml

First, declare two test jobs in your pipeline:

  1. generic_predefined_variables – prints general CI/CD variables
  2. merge_request_predefined_variables – prints merge request–specific variables
# .gitlab-ci.yml
stages:
  - test

generic_predefined_variables:
  stage: test
  script:
    - echo "GITLAB_USER_LOGIN         = $GITLAB_USER_LOGIN"
    - echo "GITLAB_USER_EMAIL         = $GITLAB_USER_EMAIL"
    - echo "CI_COMMIT_AUTHOR          = $CI_COMMIT_AUTHOR"
    - echo "CI_COMMIT_BRANCH          = $CI_COMMIT_BRANCH"
    - echo "CI_PROJECT_NAME           = $CI_PROJECT_NAME"
    - echo "CI_PROJECT_URL            = $CI_PROJECT_URL"
    - echo "CI_JOB_STAGE              = $CI_JOB_STAGE"
    - echo "CI_PIPELINE_NAME          = $CI_PIPELINE_NAME"
    - echo "CI_PIPELINE_ID            = $CI_PIPELINE_ID"
    - echo "CI_PIPELINE_SOURCE        = $CI_PIPELINE_SOURCE"

merge_request_predefined_variables:
  stage: test
  script:
    - echo "CI_MERGE_REQUEST_LABELS              = $CI_MERGE_REQUEST_LABELS"
    - echo "CI_MERGE_REQUEST_TARGET_BRANCH_NAME = $CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
    - echo "CI_MERGE_REQUEST_ASSIGNEES          = $CI_MERGE_REQUEST_ASSIGNEES"
    - echo "CI_MERGE_REQUEST_SOURCE_BRANCH_NAME = $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"
    - echo "CI_MERGE_REQUEST_TITLE              = $CI_MERGE_REQUEST_TITLE"
Job NamePurposeKey Variables
generic_predefined_variablesShow general GitLab CI/CD variablesCI_COMMIT_BRANCH, CI_PROJECT_NAME, etc.
merge_request_predefined_variablesShow merge request–only variablesCI_MERGE_REQUEST_*

Note

Predefined merge request variables like CI_MERGE_REQUEST_TITLE are only available in pipelines triggered by merge requests—not on direct pushes to branches.

2. Apply rules to Limit the Job to Merge Requests

To ensure merge_request_predefined_variables runs only for merge requests, add a rules clause that checks the pipeline source:

merge_request_predefined_variables:
  stage: test
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  script:
    - echo "CI_MERGE_REQUEST_LABELS              = $CI_MERGE_REQUEST_LABELS"
    - echo "CI_MERGE_REQUEST_TARGET_BRANCH_NAME = $CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
    - echo "CI_MERGE_REQUEST_ASSIGNEES          = $CI_MERGE_REQUEST_ASSIGNEES"
    - echo "CI_MERGE_REQUEST_SOURCE_BRANCH_NAME = $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"
    - echo "CI_MERGE_REQUEST_TITLE              = $CI_MERGE_REQUEST_TITLE"

The image shows a GitLab documentation page about CI/CD YAML syntax, specifically focusing on using rules to include or exclude jobs in pipelines. It includes a sidebar with navigation options and a detailed explanation of how rules are evaluated.

Warning

Always wrap your conditional expression in single quotes to prevent YAML parsing errors.

With this configuration, the merge-request job is included only when CI_PIPELINE_SOURCE equals merge_request_event.


3. Create a Feature Branch and Push Changes

  1. Checkout a new branch (e.g., feature-1):
    git checkout -b feature-1
  2. Commit your .gitlab-ci.yml changes and push:
    git push -u origin feature-1

In the GitLab UI, select Start a merge request when prompted.

The image shows a GitLab interface for creating a new merge request, with fields for the title, description, assignee, and reviewer. The title field is filled with "added rules for merge request job."

Because this initial push is a branch update, the merge-request job will be excluded, and only the generic job runs:

The image shows a GitLab interface displaying a list of CI/CD pipelines, with two pipelines marked as "Passed." The sidebar includes options for managing projects, code, and pipelines.


4. Open and Inspect the Merge Request Pipeline

  1. In your project, click Create merge request for feature-1.
  2. Add labels such as predefined-variables, testing-rules, then submit.

The image shows a GitLab interface for creating a new merge request, with options to assign milestones, labels, and merge options. A user is about to click the "Create merge request" button.

  1. GitLab triggers a merge request pipeline, visible under Merge requests as merge request:

The image shows a GitLab interface displaying a list of CI/CD pipelines with their statuses, including one running and two passed. The sidebar includes options like issues, merge requests, and pipelines.

  1. Open the MR pipeline. You should see only the merge_request_predefined_variables job ran successfully:

The image shows a GitLab pipeline interface for a project named "Exploring Predefined Variable Pipeline," indicating a successful pipeline run with details about jobs and merge requests.


5. Review the Merge Request Job Output

$ echo "$CI_MERGE_REQUEST_LABELS"
CI_MERGE_REQUEST_LABELS - predefined-variables,testing-rules

$ echo "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
CI_MERGE_REQUEST_TARGET_BRANCH_NAME - main

$ echo "$CI_MERGE_REQUEST_ASSIGNEES"
CI_MERGE_REQUEST_ASSIGNEES - sidd-harth

$ echo "$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"
CI_MERGE_REQUEST_SOURCE_BRANCH_NAME - feature-1

$ echo "$CI_MERGE_REQUEST_TITLE"
CI_MERGE_REQUEST_TITLE - added rules for merge request job

This confirms:

  • Merge request variables are populated only in MR pipelines.
  • The rules keyword controls when a job is executed.

In upcoming lessons, we’ll dive deeper into more advanced rules configurations and merge request integrations.


Further Reading

TopicDescriptionLink
GitLab PipelinesOverview of CI/CD in GitLabhttps://docs.gitlab.com/ee/ci/
Pipeline ConfigsWriting effective .gitlab-ci.yml fileshttps://docs.gitlab.com/ee/ci/yaml/
Merge RequestsLifecycle and best practiceshttps://docs.gitlab.com/ee/user/project/merge_requests/

Watch Video

Watch video content

Previous
Intro to Merge Requests