GitLab CI/CD Rules, Workflow, Only and Except Explained

GitLab provides two major decision layers: workflow rules determine whether a pipeline is created, while job rules determine which jobs are added and how they behave. Older only and except syntax still appears in existing configurations, but new designs should prefer rules.

Decision layers#

Rules are evaluated in order#

The first matching rule determines the job’s inclusion and relevant attributes. Put specific conditions before broad fallbacks, and make the final behavior explicit. A permissive last rule can create jobs in pipeline sources you did not intend.

Common conditions#

• Branch or tag context.
• Merge-request pipeline source.
• Scheduled, triggered, or web-created pipeline.
• File changes relevant to a component.
• Existence of files in the repository.
• Variable values for approved modes.
• Manual action for controlled deployment.

Avoid duplicate pipelines#

A branch push associated with a merge request can produce more than one pipeline if workflow and job rules are not coordinated. Decide which pipeline types the project needs, then encode that policy at workflow level before defining job-specific behavior.

Manual jobs and approvals#

A manual job is a control point, not a complete authorization system. Protect environments and branches, restrict who can run deployment jobs, use least-privilege credentials, and record the deployed artifact and approver.

Migrate from only and except#

1. Document existing behavior for branches, tags, schedules, and merge requests.
2. Create representative test cases for every pipeline source.
3. Translate one job at a time to rules.
4. Inspect the merged configuration and simulated outcomes.
5. Run on non-production references.
6. Remove old syntax only after behavior matches.

Review checklist#

• Every intended pipeline source is covered.
• Untrusted pipelines cannot access protected secrets.
• Change-based rules handle new and deleted files.
• Schedule conditions are separate from push behavior.
• A clear fallback prevents unexpected inclusion.
• Production jobs have explicit authorization and environment protection.

GitLab job rules documentation