Mastering GitLab CI/CD Rules: Triggering Jobs Based on Commit Messages

In the world of continuous integration and deployment (CI/CD), automating workflows is essential for increasing development speed and reducing errors. GitLab CI/CD provides powerful customization options through rules, which allow developers to control when and under what conditions specific jobs in a pipeline are executed.

In this blog post, we’ll explore how to use GitLab CI/CD rules to trigger jobs based on keywords in commit messages, enabling more granular control over pipeline behavior.

Understanding GitLab CI/CD Rules

GitLab CI/CD uses .gitlab-ci.yml files to define pipelines, which are made up of jobs. Each job can be configured with rules, allowing developers to determine when and under what conditions these jobs should be executed.

The rules keyword in GitLab CI/CD provides a highly flexible way to control job execution. These rules can be based on many factors, such as:

Branch names
Pipeline types (e.g., merge requests)
File changes
Commit messages

For this post, we'll focus specifically on how to trigger jobs based on commit message content, which can be extremely useful in a variety of scenarios.

Why Trigger Jobs Based on Commit Messages?

Using commit messages to control pipeline execution gives developers added flexibility. Here are a few practical use cases for this:

Triggering Special Tests or Checks: If a commit message includes certain keywords like #test, you can trigger additional tests or special validation jobs.
Deploy on Commit: Automatically trigger deployments when a commit message includes deploy.
Skipping Expensive Jobs: Commit messages could signal to skip resource-intensive jobs (e.g., performance testing or end-to-end testing) unless specific conditions are met.
Changelog or Documentation Update: Automatically update documentation or changelogs when keywords like docs or changelog are detected in commit messages.

Setting Up Rules for Commit Messages in GitLab CI/CD

To trigger jobs based on the content of a commit message, we can leverage the rules keyword in the .gitlab-ci.yml file, alongside the if condition to check for specific commit message content.

Example 1: Running a Job When the Commit Message Includes "deploy"

Suppose we want to automatically trigger a deployment job whenever a commit message includes the word deploy. Here’s how to configure it in your GitLab pipeline:

stages:
  - deploy

deploy_job:
  stage: deploy
  script:
    - echo "Deploying application..."
    - ./deploy.sh
  rules:
    - if: '$CI_COMMIT_MESSAGE =~ /deploy/i'

Explanation:

The rules block uses a regular expression ($CI_COMMIT_MESSAGE =~ /deploy/i) to check if the commit message contains the word deploy.
The /i flag makes the check case-insensitive, meaning it will match deploy, Deploy, or DEPLOY.
If the condition is met, the job will execute.

Example 2: Running Tests Based on a Specific Keyword in the Commit Message

Imagine you only want to run specific tests when the commit message contains the keyword #run-tests. This is how you can set it up:

stages:
  - test

run_tests:
  stage: test
  script:
    - echo "Running tests..."
    - ./run_tests.sh
  rules:
    - if: '$CI_COMMIT_MESSAGE =~ /#run-tests/'

In this example:

The rules condition checks whether the commit message contains the exact phrase #run-tests.
When this keyword is found, the run_tests job is triggered to run the associated test script.
If the condition is not met, the job is skipped, allowing for more flexible and efficient testing workflows.

Example 3: Skipping Jobs Based on Commit Messages

In some cases, you may want to skip certain jobs when a specific keyword is present. For instance, if your pipeline includes time-consuming jobs such as performance tests, you may want to allow developers to bypass these tests with a commit message like #skip-perf-tests.

Here’s how to skip a job based on the commit message:

stages:
  - performance

performance_tests:
  stage: performance
  script:
    - echo "Running performance tests..."
    - ./run_perf_tests.sh
  rules:
    - if: '$CI_COMMIT_MESSAGE =~ /#skip-perf-tests/'
      when: never
    - when: always

Explanation:

The first rules block checks if the commit message contains the phrase #skip-perf-tests. If the condition is met, the job will not run (when: never).
The second rule (when: always) ensures that the job runs unless explicitly skipped by the condition.
This allows developers to skip expensive jobs when necessary, giving more control over the pipeline.

Regex can't resolve environment variables

This is one important thing to note. You can not evaluate an environment variable within your regex. Although environment variables itself can be resolved it is not possible to check wether the commit message matches a regex with a variable.

There are just a few workarounds for this. The best way however remains: if you know the regex then, just put it in.

Best Practices for Using GitLab CI/CD Rules with Commit Messages

While triggering jobs based on commit messages is powerful, it’s important to apply this feature thoughtfully. Here are a few best practices to consider:

1. Keep Commit Messages Clear and Consistent

To ensure that your pipeline rules work smoothly, establish clear guidelines for commit messages across your team. This will make it easier to trigger jobs based on specific keywords, and avoid confusion about which jobs are executed and why.

2. Avoid Overcomplicating Pipelines

Using commit messages for job control is helpful, but over-reliance on this method can lead to complex pipelines that are difficult to maintain. Use this technique for special cases or exceptions rather than as a primary control mechanism for the majority of your jobs.

3. Combine Multiple Rules

You can combine multiple rules in your pipeline to account for a variety of conditions. For example, you may want a job to run only on a specific branch and when the commit message contains a certain keyword:

rules:
  - if: '$CI_COMMIT_REF_NAME == "main" && $CI_COMMIT_MESSAGE =~ /urgent-fix/'

This rule ensures that the job only runs on the main branch and when the commit message contains urgent-fix, combining branch-based logic with commit message filtering.

4. Use Regex Wisely

Regular expressions (regex) are powerful but can become complex and hard to maintain. When using regex in your rules, try to keep them simple and well-documented so that other team members can understand and modify them if necessary.

Use Cases for Commit Message-Based Job Triggers

Here are some common scenarios where triggering jobs based on commit messages can be incredibly useful:

On-Demand Deployment: Developers can trigger deployments to staging or production environments by adding a specific keyword like #deploy in the commit message.
Selective Testing: Trigger only critical tests when certain keywords (e.g., #run-tests) are present, avoiding full test suites for non-critical changes.
Hotfix Management: Automatically trigger emergency pipelines for hotfixes when commit messages contain #hotfix.
Changelog Generation: Automatically update project documentation or changelogs when the commit message includes #update-docs or #changelog.

Conclusion

By leveraging GitLab CI/CD rules based on commit messages, you can introduce more flexibility and control into your pipelines. This allows developers to trigger specific jobs or even skip certain tasks without modifying the pipeline configuration directly. Whether you're deploying code, running tests, or managing performance checks, commit message-based rules offer a lightweight, efficient solution to enhance your CI/CD workflows.

With careful implementation, this feature can streamline your processes, reduce manual intervention, and give your development team more control over what gets built and deployed—all with just a few strategic words in a commit message.

Start experimenting with GitLab CI/CD rules today, and see how commit-message-based conditions can supercharge your development pipeline!

Advanced Gitlab Course

RoyalZSoftware will release a video course about Gitlab CICD soon. A comprehensive video guide about practical examples and even building a pipeline for whitelabeled applications.

Subscribe to the newsletter to get notified about it.