Ability to set rules for triggering pipeline in entirety
Problem to solve
Sometimes you want to define rules to decide whether an entire .gitlab-ci.yml is run. The only way to do that now is to add the duplicate criteria to every single job in the workflow, and then if none of them end up resolving to true, the entire workflow is skipped. It would be more efficient if there was a global setting for a .gitlab-ci.yml that could be evaluated first.
This would also help with composability where you have less influence on the per-job rules, which could potentially cause issues where those jobs run even when you don't want anything to happen.
Another good example of where this is difficult today is with the only: merge_requests rule. You may always want to run every job for a merge request too, but there is no easy way to do this except by copy-pasting the only: merge_requests value into every single job.
Intended users
Software Developers
Proposal
We will add a new top level workflow: section that supports a single entity inside, a rules: section. In order to determine if the .gitlab-ci.yml should be triggered at all, this is evaluated first:
workflow:
rules: # this rule says that the entire pipeline should only run for merge requests, or for `master`.
- branch: master
- merge-request: yes
only_changes:
script: ...
rules: # this job will only run on changes to .rb files because it has its own rule stating so:
- changes: *.rb
always_run: # this job will always run as long as the pipeline is running, so doesn't need to add any rules.
script: ...Note that the top level workflow: evaluation is independent of the job rules: or only/except definitions. It is not re-evaluated on a per-job basis. If a job has a rules: section, it is evaluated independently of the workflow:rules section at the time the job is started.
Also, this feature builds on top of our new rules: syntax implemented here: https://gitlab.com/gitlab-org/gitlab-ce/issues/60085, but only implements the when:never: rules (if no when: is added, it treats it as a match and moves on.)
workflow: keyword name
We chose the name workflow: for the keyword because, with child/parent pipelines and other potential future features, a single .gitlab-ci.yml can represent what will be instantiated as multiple pipelines. A pipeline: keyword in this scenario would be confusing, but a workflow represents this complete combination of potential jobs and pipelines that are represented by a single .gitlab-ci.yml.
Permissions and Security
Documentation
In addition to documenting this feature on its own, we also need to update the pipelines for merge requests documentation to reference that this example can be useful for avoiding two pipelines being created (i.e., when there's a mix of merge request and general pipeline jobs):
workflow:
rules:
- branch: master
- merge-request: yes