Conditional Pipeline Execution: Run Jobs Only When Needed

WHY IT EXISTS Running every job on every commit is slow, expensive, and inefficient. A change to documentation shouldn't trigger a full backend deployment. Conditional execution was created to give you fine-grained control, ensuring that jobs only run when they are relevant, saving time and compute resources.

THE MENTAL MODEL Treat your pipeline configuration like a program with if/else logic. Instead of running a linear sequence of steps every time, you define rules that the CI/CD system evaluates. For example: "If this commit is to the main branch, then create a deploy job." Or, "If this is a merge request, then run the full test suite." This makes your pipeline smarter and more context-aware.

HOW IT WORKS In GitLab CI/CD, this is primarily handled by two keywords: workflow and rules. The workflow keyword applies globally, determining if a pipeline should be created at all. The rules keyword is defined within a specific job to control its execution. A rules block is a list of conditions evaluated in order until a match is found. A rule can specify conditions like the branch name (if: $CI_COMMIT_BRANCH == "main"), the presence of a variable, or changes to specific files. Based on the matching rule, a job can be added to the pipeline, set to run manually, or be excluded entirely.

WHEN TO USE IT Use conditional execution to create efficient, context-aware pipelines. Three common patterns: first, running different job sets for different branches (like tests on feature branches, deployments from main); second, skipping jobs if certain files haven't changed (like skipping backend tests if only documentation was updated); third, allowing manual triggers for sensitive operations like production deployments using when: manual.

WHEN NOT TO USE IT Avoid over-complicating your rules. If the logic becomes a tangled web of conditions, it's very difficult to debug why a job did or did not run. For simple pipelines where every job should run every time, explicit rules are unnecessary overhead. Be wary of creating rules that are too restrictive, as they might silently prevent important jobs from running when you expect them to.

ONE CANONICAL EXAMPLE A common scenario is deploying to production only from the main branch. In your .gitlab-ci.yml file, you would define a deploy_production job. Inside this job, you'd add a rules section. The rule would state: if: '$CI_COMMIT_BRANCH == "main"'. This condition checks if the commit is on the main branch. You would also add when: manual to this rule, ensuring a developer must manually trigger the deployment from the GitLab UI, preventing accidental deployments. Any commits to other branches would not create this job at all.