Specify when jobs run with rules

Use rules to include or exclude jobs in pipelines.

Rules are evaluated in order until the first match. When a match is found, the job is either included or excluded from the pipeline, depending on the configuration.

You cannot use dotenv variables created in job scripts in rules, because rules are evaluated before any jobs run.

Future keyword improvements are being discussed in our epic for improving rules , where anyone can add suggestions or requests.

rules examples

The following example uses if to define that the job runs in only two specific cases:

• If the pipeline is for a merge request, the first rule matches, and the job is added to the merge request pipeline with attributes of:
  • when: manual (manual job)
  • allow_failure: true (the pipeline continues running even if the manual job is not run)
  • when: on_success (default)
  • allow_failure: false (default)

  Alternatively, you can define a set of rules to exclude jobs in a few cases, but run them in all other cases:

  If you use a when clause as the final rule (not including when: never ), two simultaneous pipelines may start. Both push pipelines and merge request pipelines can be triggered by the same event (a push to the source branch for an open merge request). See how to prevent duplicate pipelines for more details.

  Run jobs for scheduled pipelines

  You can configure a job to be executed only when the pipeline has been scheduled. For example:

  In this example, make world runs in scheduled pipelines, and make build runs in branch and tag pipelines.

  Skip jobs if the branch is empty

  • Doesn’t have changed files, the job doesn’t run.
  • Has changed files, the job runs.

  For example, in a project with main as the default branch:

   The rule for this job compares all files and paths in the current branch recursively ( **/* ) against the main branch. The rule matches and the job runs only when there are changes to the files in the branch.

  Common if clauses with predefined variables

  The following example runs the job as a manual job in scheduled pipelines or in push pipelines (to branches or tags), with when: on_success (default). It does not add the job to any other pipeline type.

  The following example runs the job as a when: on_success job in merge request pipelines and scheduled pipelines. It does not run in any other pipeline type.

  • if: $CI_COMMIT_TAG : If changes are pushed for a tag.
  • if: $CI_COMMIT_BRANCH : If changes are pushed to any branch.
  • if: $CI_COMMIT_BRANCH == "main" : If changes are pushed to main .
  • if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH : If changes are pushed to the default branch. Use when you want to have the same configuration in multiple projects with different default branches.
  • if: $CI_COMMIT_BRANCH =~ /regex-expression/ : If the commit branch matches a regular expression.
  • if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $CI_COMMIT_TITLE =~ /Merge branch.*/ : If the commit branch is the default branch and the commit message title matches a regular expression. For example, the default commit message for a merge commit starts with Merge branch .
  • if: $CUSTOM_VARIABLE == "value1" : If the custom variable CUSTOM_VARIABLE is exactly value1 .

  Run jobs only in specific pipeline types

  You can use predefined CI/CD variables with rules to choose which pipeline types jobs should run for.

  • Branch pipelines that run for Git push events to a branch, like new commits or tags.
  • Tag pipelines that run only when a new Git tag is pushed to a branch.
  • Merge request pipelines that run for changes to a merge request, like new commits or selecting Run pipeline in a merge request’s pipelines tab.
  • Scheduled pipelines.

  For example, to configure a job to run for merge request pipelines and scheduled pipelines, but not branch or tag pipelines:

     CI_PIPELINE_SOURCE predefined variable 

  Use the CI_PIPELINE_SOURCE variable to control when to add jobs for these pipeline types:

  These values are the same as returned for the source parameter when using the pipelines API endpoint.

  Complex rules

  You can use all rules keywords, like if , changes , and exists , in the same rule. The rule evaluates to true only when all included keywords evaluate to true.

     If the Dockerfile file or any file in /docker/scripts has changed and $VAR == “string value”, then the job runs manually and is allowed to fail.

  You can use parentheses with && and || to build more complicated variable expressions.

  Avoid duplicate pipelines

  If a job uses rules , a single action, like pushing a commit to a branch, can trigger multiple pipelines. You don’t have to explicitly configure rules for multiple types of pipeline to trigger them accidentally.

  Some configurations that have the potential to cause duplicate pipelines cause a pipeline warning to be displayed.

    This job does not run when $CUSTOM_VARIABLE is false, but it does run in all other pipelines, including both push (branch) and merge request pipelines. With this configuration, every push to an open merge request’s source branch causes duplicated pipelines.

  Use workflow to specify which types of pipelines can run.

  Rewrite the rules to run the job only in very specific cases, and avoid a final when rule:

  You can also avoid duplicate pipelines by changing the job rules to avoid either push (branch) pipelines or merge request pipelines. However, if you use a - when: always rule without workflow: rules , GitLab still displays a pipeline warning.

  For example, the following does not trigger double pipelines, but is not recommended without workflow: rules :

    You should not include both push and merge request pipelines in the same job without workflow:rules that prevent duplicate pipelines:

  Also, do not mix only/except jobs with rules jobs in the same pipeline. It may not cause YAML errors, but the different default behaviors of only/except and rules can cause issues that are difficult to troubleshoot:

  For every change pushed to the branch, duplicate pipelines run. One branch pipeline runs a single job ( job-with-no-rules ), and one merge request pipeline runs the other job ( job-with-rules ). Jobs with no rules default to except: merge_requests , so job-with-no-rules runs in all cases except merge requests.

  Reuse rules in different jobs

  Use !reference tags to reuse rules in different jobs. You can combine !reference rules with regular job-defined rules. For example:

  CI/CD variable expressions

  Use variable expressions with rules:if to control when jobs should be added to a pipeline.

  • if: $VARIABLE == "some value"
  • if: $VARIABLE != "some value"
  • if: $VARIABLE_1 == $VARIABLE_2
  • if: $VARIABLE_1 != $VARIABLE_2
  • if: $VARIABLE == null
  • if: $VARIABLE != null
  • if: $VARIABLE == ""
  • if: $VARIABLE != ""
  • if: $VARIABLE

  Compare a variable to a regular expression

  You can do regular expression matching on variable values with the =~ and !~ operators. Variable pattern matching with regular expressions uses the RE2 regular expression syntax.

  • Matches are found when using =~ .
  • Matches are not found when using !~ .
  • if: $VARIABLE =~ /^content.*/
  • if: $VARIABLE !~ /^content.*/
  • Single-character regular expressions, like /./ , are not supported and produce an invalid expression syntax error.
  • Pattern matching is case-sensitive by default. Use the i flag modifier to make a pattern case-insensitive. For example: /pattern/i .
  • Only the tag or branch name can be matched by a regular expression. The repository path, if given, is always matched literally.
  • The entire pattern must be surrounded by / . For example, you can’t use issue-/.*/ to match all tag names or branch names that begin with issue- , but you can use /issue-.*/ .
  • The @ symbol denotes the beginning of a ref’s repository path. To match a ref name that contains the @ character in a regular expression, you must use the hex character code match \x40 .
  • Use anchors ^ and $ to avoid the regular expression matching only a substring of the tag name or branch name. For example, /^issue-.*$/ is equivalent to /^issue-/ , while just /issue/ would also match a branch called severe-issues .

  Store a regular expression in a variable

  History
  • Introduced in GitLab 15.0 with a flag named ci_fix_rules_if_comparison_with_regexp_variable , disabled by default.
  • Generally available and feature flag ci_fix_rules_if_comparison_with_regexp_variable removed in GitLab 15.1.

  Variables on the right side of =~ and !~ expressions are evaluated as regular expressions. The regular expression must be enclosed in forward slashes ( / ). For example:

   Variables in a regular expression are not resolved. For example:

  • $VARIABLE1 =~ /^content.*/ && $VARIABLE2 == "something"
  • $VARIABLE1 =~ /^content.*/ && $VARIABLE2 =~ /thing$/ && $VARIABLE3
  • $VARIABLE1 =~ /^content.*/ || $VARIABLE2 =~ /thing$/ && $VARIABLE3

  The precedence of operators follows the Ruby 2.5 standard, so && evaluates before || .

  You can use parentheses to group expressions together. Parentheses take precedence over && and || , so expressions enclosed in parentheses evaluate first, and the result is used for the rest of the expression.

  • ($VARIABLE1 =~ /^content.*/ || $VARIABLE2) && ($VARIABLE3 =~ /thing$/ || $VARIABLE4)
  • ($VARIABLE1 =~ /^content.*/ || $VARIABLE2 =~ /thing$/) && $VARIABLE3
  • $CI_COMMIT_BRANCH == "my-branch" || (($VARIABLE1 == "thing" || $VARIABLE2 == "thing") && $VARIABLE3)

  Troubleshooting

  Unexpected behavior from regular expression matching with =~

  When using the =~ character, make sure the right side of the comparison always contains a valid regular expression.

  If the right side of the comparison is not a valid regular expression enclosed with / characters, the expression evaluates in an unexpected way. In that case, the comparison checks if the left side is a substring of the right side. For example, "23" =~ "1234" evaluates to true, which is the opposite of "23" =~ /1234/ , which evaluates to false.

  You should not configure your pipeline to rely on this behavior.

  Help & feedback

  Docs

  Edit this page to fix an error or add an improvement in a merge request.
  Create an issue to suggest an improvement to this page.
  

  Product

  Create an issue if there's something you don't like about this feature.
  Propose functionality by submitting a feature request.
  Join First Look to help shape new features.

  Feature availability and product trials

  View pricing to see all GitLab tiers and features, or to upgrade.
  Try GitLab for free with access to all features for 30 days.
  

  Get Help

  If you didn't find what you were looking for, search the docs.
  

  If you want help with something specific and could use community support, post on the GitLab forum.
  

  For problems setting up or using this feature (depending on your GitLab subscription).