GitLab "rules" and "only/except" Cannot Be Used Together

By Kaveh Alemi·Latchkey

rules is the modern replacement for only/except, and GitLab refuses to let a single job declare both. The job names the conflicting keyword.

What this error means

Validation fails naming the job and the conflicting key: "config key may not be used with rules: only" (or except). The pipeline is rejected outright.

This GitLab CI configuration is invalid:
jobs:test config key may not be used with `rules`: only

Common causes

A job declares both rules and only/except

A job migrated to rules that still carries a leftover only: or except: block triggers the conflict - the two mechanisms cannot coexist on one job.

only/except inherited from default or a template

A default: or extended template that sets only/except collides when the job adds its own rules, even though neither alone is wrong.

How to fix it

Convert the job fully to rules

Remove only/except and express the same conditions with rules.

test:
  script: make test
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == "main"'

Clear inherited only/except

1. Check default: and any extended template for only/except.
2. Move that logic into rules at the template level, or override it per job.
3. Re-validate; no job should mix the two mechanisms.

How to prevent it

• Standardize on rules; treat only/except as legacy to remove.
• Audit templates and default: for stray only/except.
• Validate in the Pipeline Editor after migrating any job.

Frequently asked questions

Related guides

References

• GitHub Actions documentation