Use rules at Workflow Level

GitLab CI/CD lets you define rules at both the job and workflow levels. While job-level rules determine whether an individual job runs, workflow-level rules control if the entire pipeline is created. This approach helps you:

• Dynamically set variables.
• Match branch patterns using regex.
• Filter pipelines by file changes.

In this guide, you’ll learn how to implement workflow-level rules with real examples.

Prerequisites

1. Create a new GitLab project under your demos group.
2. Name it generic-project (public) and initialize with a README.md.
3. Open CI/CD > Editor to configure your pipeline.

1. Initial Pipeline Configuration

Add a minimal .gitlab-ci.yml to ensure your project has a pipeline:

workflow:
  name: Exploring GitLab CI Concepts

deploy-job:
  script:
    - echo "Deploying application..."
    - echo "Application successfully deployed to $DEPLOY_VARIABLE environment"

By default, no variables are set and the pipeline always runs. Let’s introduce workflow-level rules to change that.

2. Rule 1: Run Only on main

Trigger the pipeline only for pushes to main, and set DEPLOY_VARIABLE to PRODUCTION:

workflow:
  name: Exploring GitLab CI Concepts
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      variables:
        DEPLOY_VARIABLE: "PRODUCTION"

deploy-job:
  script:
    - echo "Deploying application..."
    - echo "Application successfully deployed to $DEPLOY_VARIABLE environment"

When you push to main:

$ echo "Deploying application..."
Deploying application...
$ echo "Application successfully deployed to $DEPLOY_VARIABLE environment"
Application successfully deployed to PRODUCTION environment

3. Rule 2: Merge Requests from feature/*

Only run pipelines on merge requests whose source branch matches feature/*. Use the predefined variable CI_MERGE_REQUEST_SOURCE_BRANCH_NAME:

workflow:
  name: Exploring GitLab CI Concepts
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      variables:
        DEPLOY_VARIABLE: "PRODUCTION"
    - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature\// && $CI_PIPELINE_SOURCE == "merge_request_event"'
      variables:
        DEPLOY_VARIABLE: "TESTING"

deploy-job:
  script:
    - echo "Deploying application..."
    - echo "Application successfully deployed to $DEPLOY_VARIABLE environment"

Push to feature/my-awesome-feature and create an MR:

No pipeline runs yet because we haven’t introduced file-change filters.

4. Rule 3: File-Change Filtering

Use the changes: keyword to trigger pipelines only when certain files are modified. For example, run MR pipelines only if README.md changes:

workflow:
  name: Exploring GitLab CI Concepts
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      variables:
        DEPLOY_VARIABLE: "PRODUCTION"
    - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature\// && $CI_PIPELINE_SOURCE == "merge_request_event"'
      changes:
        - README.md
      variables:
        DEPLOY_VARIABLE: "TESTING"

deploy-job:
  script:
    - echo "Deploying application..."
    - echo "Application successfully deployed to $DEPLOY_VARIABLE environment"

Update README.md in your feature branch and push. Now you’ll see a new pipeline:

The job log confirms the TESTING variable:

$ echo "Deploying application..."
Deploying application...
$ echo "Application successfully deployed to $DEPLOY_VARIABLE environment"
Application successfully deployed to TESTING environment

Summary of Workflow-Level Rules

Final .gitlab-ci.yml Example

workflow:
  name: Exploring GitLab CI Concepts
  rules:
    - if: '$CI_COMMIT_TITLE =~ /-draft$/'
      when: never
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

deploy-job:
  script:
    - echo "Deploying application..."
    - echo "Application successfully deployed to $DEPLOY_VARIABLE environment"

Links and References

• GitLab CI/CD documentation
• Predefined CI/CD variables
• Rules keyword reference