How to Define Workflow Rules in GitLab CI

When working with GitLab CI/CD, workflow:rules help control whether a pipeline should run at all. It’s important to understand how these rules work because they differ from regular job rules, especially when it comes to supported syntax.

✅ What You Can Do in workflow:rules

• Use basic comparisons like == or !=
• Use logical conditions with && and ||
• Use functions like startsWith($VARIABLE, "value")
• Use $CI_COMMIT_BRANCH, $CI_COMMIT_TAG, and similar predefined variables
• Wrap the full condition in single quotes

Example:

workflow:
  rules:
    - if: '$CI_COMMIT_BRANCH == "main" || startsWith($CI_COMMIT_BRANCH, "feature/")'
      when: always
    - when: never

❌ What You Can’t Do in workflow:rules

• No regular expressions (e.g., =~ /pattern/) — these only work in job-level rules
• No complex YAML syntax like nested objects inside if
• No unquoted expressions — always quote the full condition

💡 Pro Tip:

If you need to skip certain runs based on the commit message (e.g., [nopublish]), do that inside job rules, not workflow:rules.

some_job:
  rules:
    - if: '$CI_COMMIT_MESSAGE =~ /\\[nopublish\\]/'
      when: never
    - when: always

Conclusion

Use workflow:rules to define when a pipeline runs, based on simple branch or tag conditions. Keep regex and detailed logic in job-level rules to avoid syntax errors.