diff options
Diffstat (limited to 'doc/source/tenants.rst')
| -rw-r--r-- | doc/source/tenants.rst | 111 |
1 files changed, 111 insertions, 0 deletions
diff --git a/doc/source/tenants.rst b/doc/source/tenants.rst index 7835eef46..fbbb458a5 100644 --- a/doc/source/tenants.rst +++ b/doc/source/tenants.rst @@ -211,6 +211,66 @@ configuration. Some examples of tenant definitions are: exclude-unprotected-branches. This currently only affects GitHub and GitLab projects. + .. attr:: include-branches + + A list of regexes matching branches which should be + processed. If omitted, all branches are included. + Operates after *exclude-unprotected-branches* and so may + be used to further reduce the set of branches (but not + increase it). + + It has priority over *exclude-branches*. + + .. attr:: exclude-branches + + A list of regexes matching branches which should be + processed. If omitted, all branches are included. + Operates after *exclude-unprotected-branches* and so may + be used to further reduce the set of branches (but not + increase it). + + It will not exclude a branch which already matched + *include-branches*. + + .. attr:: always-dynamic-branches + + A list of regular expressions matching branches which + should be treated as if every change newly proposes + dynamic Zuul configuration. In other words, the only time + Zuul will realize any configuration related to these + branches is during the time it is running jobs for a + proposed change. + + This is potentially useful for situations with large + numbers of rarely used feature branches, but comes at the + cost of a significant reduction in Zuul features for these + branches. + + Every regular expression listed here will also implicitly + be included in *exclude-branches*, therefore Zuul will not + load any static in-repo configuration from this branch. + These branches will not be available for use in overriding + checkouts of repos, nor will they be included in the git + repos that Zuul prepares for *required-projects* (unless + there is a change in the dependency tree for this branch). + + In particular, this means that the only jobs which can be + specified for these branches are pre-merge and gating jobs + (such as :term:`check` and :term:`gate`). No post-merge + or periodic jobs will run for these branches. + + Using this setting also incurs additional processing for + each change submitted for these branches as Zuul must + recalculate the configuration layout it uses for such a + change as if it included a change to a ``zuul.yaml`` file, + even if the change does not alter the configuration). + + With all these caveats in mind, this can be useful for + repos with large numbers of rarely used branches as it + allows Zuul to omit their configuration in most + circumstances and only calculate the configuration of a + single additional branch when it is used. + .. attr:: extra-config-paths Normally Zuul loads in-repo configuration from the first @@ -363,6 +423,57 @@ configuration. Some examples of tenant definitions are: to add finer filtering to admin rules, for example filtering by the ``iss`` claim (generally equal to the issuer ID). + .. attr:: semaphores + + A list of names of :attr:`global-semaphore` objects to allow + jobs in this tenant to access. + +.. _global_semaphore: + +Global Semaphore +---------------- + +Semaphores are normally defined in in-repo configuration (see +:ref:`semaphore`), however to support use-cases where semaphores are +used to represent constrained global resources that may be used by +multiple Zuul tenants, semaphores may be defined within the main +tenant configuration file. + +In order for a job to use a global semaphore, the semaphore must first +be defined in the tenant configuration file with +:attr:`global-semaphore` and then added to each tenant which should +have access to it with :attr:`tenant.semaphores`. Once that is done, +Zuul jobs may use that semaphore in the same way they would use a +normal tenant-scoped semaphore. + +If any tenant which is granted access to a global semaphore also has a +tenant-scoped semaphore defined with the same name, that definition +will be treated as a configuration error and subsequently ignored in +favor of the global semaphore. + +An example definition looks similar to the normal semaphore object: + +.. code-block:: yaml + + - global-semaphore: + name: global-semaphore-foo + max: 5 + +.. attr:: global-semaphore + + The following attributes are available: + + .. attr:: name + :required: + + The name of the semaphore, referenced by jobs. + + .. attr:: max + :default: 1 + + The maximum number of running jobs which can use this semaphore. + + .. _admin_rule_definition: Access Rule |