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.
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
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
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