workflow keyword (FREE)
workflow keyword to control when pipelines are created.
workflow keyword is evaluated before jobs. For example, if a job is configured to run
for tags, but the workflow prevents tag pipelines, the job never runs.
if clauses for
if clauses for
||Control when merge request pipelines run.|
||Control when both branch pipelines and tag pipelines run.|
||Control when tag pipelines run.|
||Control when branch pipelines run.|
See the common
if clauses for
rules for more examples.
workflow: rules examples
In the following example:
- Pipelines run for all
pushevents (changes to branches and new tags).
- Pipelines for push events with commit messages that end with
-draftdon't run, because they are set to
- Pipelines for schedules or merge requests don't run either, because no rules evaluate to true for them.
workflow: rules: - if: $CI_COMMIT_MESSAGE =~ /-draft$/ when: never - if: $CI_PIPELINE_SOURCE == "push"
This example has strict rules, and pipelines do not run in any other case.
Alternatively, all of the rules can be
when: never, with a final
when: always rule. Pipelines that match the
when: never rules do not run.
All other pipeline types run. For example:
workflow: rules: - if: $CI_PIPELINE_SOURCE == "schedule" when: never - if: $CI_PIPELINE_SOURCE == "push" when: never - when: always
This example prevents pipelines for schedules or
push (branches and tags) pipelines.
when: always rule runs all other pipeline types, including merge
Switch between branch pipelines and merge request pipelines
Introduced in GitLab 13.8.
To make the pipeline switch from branch pipelines to merge request pipelines after
a merge request is created, add a
workflow: rules section to your
The following example is for a project that runs branch and merge request pipelines only, but does not run pipelines for any other case. It runs:
- Branch pipelines when a merge request is not open for the branch.
- Merge request pipelines when a merge request is open for the branch.
workflow: rules: - if: $CI_PIPELINE_SOURCE == "merge_request_event" - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS when: never - if: $CI_COMMIT_BRANCH
If GitLab attempts to trigger:
- A merge request pipeline, start the pipeline. For example, a merge request pipeline can be triggered by a push to a branch with an associated open merge request.
- A branch pipeline, but a merge request is open for that branch, do not run the branch pipeline. For example, a branch pipeline can be triggered by a change to a branch, an API call, a scheduled pipeline, and so on.
- A branch pipeline, but there is no merge request open for the branch, run the branch pipeline.
You can also add a rule to an existing
workflow section to switch from branch pipelines
to merge request pipelines when a merge request is created.
Add this rule to the top of the
workflow section, followed by the other rules that
were already present:
workflow: rules: - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push" when: never - ... # Previously defined workflow rules here
Triggered pipelines that run on a branch have a
set and could be blocked by a similar rule. Triggered pipelines have a pipeline source
&& $CI_PIPELINE_SOURCE == "push" ensures the rule
does not block triggered pipelines.
Git Flow with merge request pipelines
You can use
workflow: rules as part of Git Flow or similar strategies
with merge request pipelines. With these rules, you can use merge request pipeline features
with feature branches, while keeping long-lived branches to support multiple versions
of your software.
For example, to only run pipelines for your merge requests, tags, and protected branches:
workflow: rules: - if: $CI_PIPELINE_SOURCE == "merge_request_event" - if: $CI_COMMIT_TAG - if: $CI_COMMIT_REF_PROTECTED == "true"
This example assumes that your long-lived branches are protected.
Introduced in GitLab 13.0.
GitLab provides templates that set up
for common scenarios. These templates help prevent duplicate pipelines.
makes your pipelines run for branches and tags.
Branch pipeline status is displayed in merge requests that use the branch as a source. However, this pipeline type does not support any features offered by merge request pipelines, like merged results pipelines or merge trains. This template intentionally avoids those features.
To include it:
include: - template: 'Workflows/Branch-Pipelines.gitlab-ci.yml'
makes your pipelines run for the default branch, tags, and
all types of merge request pipelines. Use this template if you use any of the
the merge request pipelines features.
To include it:
include: - template: 'Workflows/MergeRequest-Pipelines.gitlab-ci.yml'
Merge request stuck with
Checking pipeline status. message
If a merge request displays
Checking pipeline status., but the message never goes
away (the "spinner" never stops spinning), it might be due to
This issue can happen if a project has Pipelines must succeed
enabled, but the
workflow:rules prevent a pipeline from running for the merge request.
For example, with this workflow, merge requests cannot be merged, because no pipeline can run:
workflow: rules: - changes: - .gitlab/**/**.md when: never