How to Use rules for Conditional Jobs in GitLab CI/CD

rules evaluates a list of conditions top to bottom and the first match decides whether and how the job runs.

Add a rules: list to a job. Each entry can test if, changes, or exists, and set when to run, skip, or make the job manual.

Steps

• List rules: entries in priority order.
• Use if to test variables like $CI_COMMIT_BRANCH.
• Set when: never to exclude, or when: manual to gate a job.

Pipeline

deploy:
  script: ./deploy.sh
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: on_success
    - if: '$CI_COMMIT_BRANCH == "staging"'
      when: manual
    - when: never

Gotchas

• The first matching rule wins; later rules are ignored, so order matters.
• If no rule matches and there is no final catch-all, the job is not added to the pipeline.

Related guides