James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 1 | :title: Project Configuration |
| 2 | |
| 3 | .. _project-config: |
| 4 | |
| 5 | Project Configuration |
| 6 | ===================== |
| 7 | |
| 8 | The following sections describe the main part of Zuul's configuration. |
| 9 | All of what follows is found within files inside of the repositories |
| 10 | that Zuul manages. |
| 11 | |
| 12 | Security Contexts |
| 13 | ----------------- |
| 14 | |
| 15 | When a system administrator configures Zuul to operate on a project, |
| 16 | they specify one of two security contexts for that project. A |
| 17 | *config-project* is one which is primarily tasked with holding |
| 18 | configuration information and job content for Zuul. Jobs which are |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 19 | defined in a config-project are run with elevated privileges, and all |
| 20 | Zuul configuration items are available for use. It is expected that |
| 21 | changes to config-projects will undergo careful scrutiny before being |
| 22 | merged. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 23 | |
| 24 | An *untrusted-project* is a project whose primary focus is not to |
| 25 | operate Zuul, but rather it is one of the projects being tested or |
| 26 | deployed. The Zuul configuration language available to these projects |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 27 | is somewhat restricted (as detailed in individual sections below), and |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 28 | jobs defined in these projects run in a restricted execution |
| 29 | environment since they may be operating on changes which have not yet |
| 30 | undergone review. |
| 31 | |
| 32 | Configuration Loading |
| 33 | --------------------- |
| 34 | |
| 35 | When Zuul starts, it examines all of the git repositories which are |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 36 | specified by the system administrator in :ref:`tenant-config` and |
| 37 | searches for files in the root of each repository. Zuul looks first |
| 38 | for a file named ``zuul.yaml`` or a directory named ``zuul.d``, and if |
| 39 | they are not found, ``.zuul.yaml`` or ``.zuul.d`` (with a leading |
| 40 | dot). In the case of an :term:`untrusted-project`, the configuration |
| 41 | from every branch is included, however, in the case of a |
| 42 | :term:`config-project`, only the ``master`` branch is examined. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 43 | |
| 44 | When a change is proposed to one of these files in an |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 45 | untrusted-project, the configuration proposed in the change is merged |
| 46 | into the running configuration so that any changes to Zuul's |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 47 | configuration are self-testing as part of that change. If there is a |
| 48 | configuration error, no jobs will be run and the error will be |
| 49 | reported by any applicable pipelines. In the case of a change to a |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 50 | config-project, the new configuration is parsed and examined for |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 51 | errors, but the new configuration is not used in testing the change. |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 52 | This is because configuration in config-projects is able to access |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 53 | elevated privileges and should always be reviewed before being merged. |
| 54 | |
| 55 | As soon as a change containing a Zuul configuration change merges to |
| 56 | any Zuul-managed repository, the new configuration takes effect |
| 57 | immediately. |
| 58 | |
| 59 | Configuration Items |
| 60 | ------------------- |
| 61 | |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 62 | The ``zuul.yaml`` and ``.zuul.yaml`` configuration files are |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 63 | YAML-formatted and are structured as a series of items, each of which |
| 64 | is described below. |
| 65 | |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 66 | In the case of a ``zuul.d`` directory, Zuul recurses the directory and |
| 67 | extends the configuration using all the .yaml files in the sorted path |
| 68 | order. For example, to keep job's variants in a separate file, it |
| 69 | needs to be loaded after the main entries, for example using number |
| 70 | prefixes in file's names:: |
Tristan Cacqueray | 4a01583 | 2017-07-11 05:18:14 +0000 | [diff] [blame] | 71 | |
| 72 | * zuul.d/pipelines.yaml |
| 73 | * zuul.d/projects.yaml |
| 74 | * zuul.d/01_jobs.yaml |
| 75 | * zuul.d/02_jobs-variants.yaml |
| 76 | |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 77 | .. _pipeline: |
| 78 | |
| 79 | Pipeline |
| 80 | ~~~~~~~~ |
| 81 | |
| 82 | A pipeline describes a workflow operation in Zuul. It associates jobs |
| 83 | for a given project with triggering and reporting events. |
| 84 | |
| 85 | Its flexible configuration allows for characterizing any number of |
| 86 | workflows, and by specifying each as a named configuration, makes it |
| 87 | easy to apply similar workflow operations to projects or groups of |
| 88 | projects. |
| 89 | |
| 90 | By way of example, one of the primary uses of Zuul is to perform |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 91 | project gating. To do so, one can create a :term:`gate` pipeline |
| 92 | which tells Zuul that when a certain event (such as approval by a code |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 93 | reviewer) occurs, the corresponding change or pull request should be |
| 94 | enqueued into the pipeline. When that happens, the jobs which have |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 95 | been configured to run for that project in the gate pipeline are run, |
| 96 | and when they complete, the pipeline reports the results to the user. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 97 | |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 98 | Pipeline configuration items may only appear in :term:`config-projects |
| 99 | <config-project>`. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 100 | |
| 101 | Generally, a Zuul administrator would define a small number of |
| 102 | pipelines which represent the workflow processes used in their |
| 103 | environment. Each project can then be added to the available |
| 104 | pipelines as appropriate. |
| 105 | |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 106 | Here is an example :term:`check` pipeline, which runs whenever a new |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 107 | patchset is created in Gerrit. If the associated jobs all report |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 108 | success, the pipeline reports back to Gerrit with ``Verified`` vote of |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 109 | +1, or if at least one of them fails, a -1: |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 110 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 111 | .. code-block:: yaml |
| 112 | |
| 113 | - pipeline: |
| 114 | name: check |
| 115 | manager: independent |
| 116 | trigger: |
| 117 | my_gerrit: |
| 118 | - event: patchset-created |
| 119 | success: |
| 120 | my_gerrit: |
| 121 | Verified: 1 |
| 122 | failure: |
| 123 | my_gerrit |
| 124 | Verified: -1 |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 125 | |
James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 126 | .. TODO: See TODO for more annotated examples of common pipeline configurations. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 127 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 128 | .. attr:: pipeline |
James E. Blair | 7145c58 | 2017-07-26 13:30:39 -0700 | [diff] [blame] | 129 | |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 130 | The attributes available on a pipeline are as follows (all are |
| 131 | optional unless otherwise specified): |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 132 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 133 | .. attr:: name |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 134 | :required: |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 135 | |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 136 | This is used later in the project definition to indicate what jobs |
| 137 | should be run for events in the pipeline. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 138 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 139 | .. attr:: manager |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 140 | :required: |
James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 141 | |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 142 | There are currently two schemes for managing pipelines: |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 143 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 144 | .. value:: independent |
James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 145 | |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 146 | Every event in this pipeline should be treated as independent |
| 147 | of other events in the pipeline. This is appropriate when |
| 148 | the order of events in the pipeline doesn't matter because |
| 149 | the results of the actions this pipeline performs can not |
| 150 | affect other events in the pipeline. For example, when a |
| 151 | change is first uploaded for review, you may want to run |
| 152 | tests on that change to provide early feedback to reviewers. |
| 153 | At the end of the tests, the change is not going to be |
| 154 | merged, so it is safe to run these tests in parallel without |
| 155 | regard to any other changes in the pipeline. They are |
| 156 | independent. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 157 | |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 158 | Another type of pipeline that is independent is a post-merge |
| 159 | pipeline. In that case, the changes have already merged, so |
| 160 | the results can not affect any other events in the pipeline. |
James E. Blair | 1761e86 | 2017-07-25 16:15:47 -0700 | [diff] [blame] | 161 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 162 | .. value:: dependent |
James E. Blair | 1761e86 | 2017-07-25 16:15:47 -0700 | [diff] [blame] | 163 | |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 164 | The dependent pipeline manager is designed for gating. It |
| 165 | ensures that every change is tested exactly as it is going to |
| 166 | be merged into the repository. An ideal gating system would |
| 167 | test one change at a time, applied to the tip of the |
| 168 | repository, and only if that change passed tests would it be |
| 169 | merged. Then the next change in line would be tested the |
| 170 | same way. In order to achieve parallel testing of changes, |
| 171 | the dependent pipeline manager performs speculative execution |
| 172 | on changes. It orders changes based on their entry into the |
| 173 | pipeline. It begins testing all changes in parallel, |
| 174 | assuming that each change ahead in the pipeline will pass its |
| 175 | tests. If they all succeed, all the changes can be tested |
| 176 | and merged in parallel. If a change near the front of the |
| 177 | pipeline fails its tests, each change behind it ignores |
| 178 | whatever tests have been completed and are tested again |
| 179 | without the change in front. This way gate tests may run in |
| 180 | parallel but still be tested correctly, exactly as they will |
| 181 | appear in the repository when merged. |
James E. Blair | 1761e86 | 2017-07-25 16:15:47 -0700 | [diff] [blame] | 182 | |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 183 | For more detail on the theory and operation of Zuul's |
| 184 | dependent pipeline manager, see: :doc:`gating`. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 185 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 186 | .. attr:: allow-secrets |
James E. Blair | f17aa9c | 2017-07-05 13:21:23 -0700 | [diff] [blame] | 187 | |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 188 | This is a boolean which can be used to prevent jobs which |
| 189 | require secrets from running in this pipeline. Some pipelines |
| 190 | run on proposed changes and therefore execute code which has not |
| 191 | yet been reviewed. In such a case, allowing a job to use a |
| 192 | secret could result in that secret being exposed. The default |
| 193 | is False, meaning that in order to run jobs with secrets, this |
| 194 | must be explicitly enabled on each Pipeline where that is safe. |
James E. Blair | f17aa9c | 2017-07-05 13:21:23 -0700 | [diff] [blame] | 195 | |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 196 | For more information, see :ref:`secret`. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 197 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 198 | .. attr:: description |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 199 | |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 200 | This field may be used to provide a textual description of the |
| 201 | pipeline. It may appear in the status page or in documentation. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 202 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 203 | .. attr:: success-message |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 204 | |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 205 | The introductory text in reports when all the voting jobs are |
| 206 | successful. Defaults to "Build successful." |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 207 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 208 | .. attr:: failure-message |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 209 | |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 210 | The introductory text in reports when at least one voting job |
| 211 | fails. Defaults to "Build failed." |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 212 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 213 | .. attr:: merge-failure-message |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 214 | |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 215 | The introductory text in the message reported when a change |
| 216 | fails to merge with the current state of the repository. |
| 217 | Defaults to "Merge failed." |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 218 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 219 | .. attr:: footer-message |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 220 | |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 221 | Supplies additional information after test results. Useful for |
| 222 | adding information about the CI system such as debugging and |
| 223 | contact details. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 224 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 225 | .. attr:: trigger |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 226 | |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 227 | At least one trigger source must be supplied for each pipeline. |
| 228 | Triggers are not exclusive -- matching events may be placed in |
| 229 | multiple pipelines, and they will behave independently in each |
| 230 | of the pipelines they match. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 231 | |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 232 | Triggers are loaded from their connection name. The driver type |
| 233 | of the connection will dictate which options are available. See |
| 234 | :ref:`drivers`. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 235 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 236 | .. attr:: require |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 237 | |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 238 | If this section is present, it establishes prerequisites for |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 239 | any kind of item entering the Pipeline. Regardless of how the |
| 240 | item is to be enqueued (via any trigger or automatic dependency |
| 241 | resolution), the conditions specified here must be met or the |
James E. Blair | d134c6d | 2017-07-26 16:09:34 -0700 | [diff] [blame] | 242 | item will not be enqueued. These requirements may vary |
| 243 | depending on the source of the item being enqueued. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 244 | |
James E. Blair | d134c6d | 2017-07-26 16:09:34 -0700 | [diff] [blame] | 245 | Requirements are loaded from their connection name. The driver |
| 246 | type of the connection will dictate which options are available. |
| 247 | See :ref:`drivers`. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 248 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 249 | .. attr:: reject |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 250 | |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 251 | If this section is present, it establishes prerequisites that |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 252 | can block an item from being enqueued. It can be considered a |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 253 | negative version of :attr:`pipeline.require`. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 254 | |
James E. Blair | d134c6d | 2017-07-26 16:09:34 -0700 | [diff] [blame] | 255 | Requirements are loaded from their connection name. The driver |
| 256 | type of the connection will dictate which options are available. |
| 257 | See :ref:`drivers`. |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 258 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 259 | .. attr:: dequeue-on-new-patchset |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 260 | |
| 261 | Normally, if a new patchset is uploaded to a change that is in a |
| 262 | pipeline, the existing entry in the pipeline will be removed |
| 263 | (with jobs canceled and any dependent changes that can no longer |
| 264 | merge as well. To suppress this behavior (and allow jobs to |
| 265 | continue running), set this to ``false``. Default: ``true``. |
| 266 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 267 | .. attr:: ignore-dependencies |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 268 | |
| 269 | In any kind of pipeline (dependent or independent), Zuul will |
| 270 | attempt to enqueue all dependencies ahead of the current change |
| 271 | so that they are tested together (independent pipelines report |
| 272 | the results of each change regardless of the results of changes |
| 273 | ahead). To ignore dependencies completely in an independent |
| 274 | pipeline, set this to ``true``. This option is ignored by |
| 275 | dependent pipelines. The default is: ``false``. |
| 276 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 277 | .. attr:: precedence |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 278 | |
| 279 | Indicates how the build scheduler should prioritize jobs for |
| 280 | different pipelines. Each pipeline may have one precedence, |
| 281 | jobs for pipelines with a higher precedence will be run before |
| 282 | ones with lower. The value should be one of ``high``, |
| 283 | ``normal``, or ``low``. Default: ``normal``. |
| 284 | |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 285 | .. _reporters: |
| 286 | |
| 287 | The following options configure :term:`reporters <reporter>`. |
| 288 | Reporters are complementary to triggers; where a trigger is an |
| 289 | event on a connection which causes Zuul to enqueue an item, a |
| 290 | reporter is the action performed on a connection when an item is |
| 291 | dequeued after its jobs complete. The actual syntax for a reporter |
| 292 | is defined by the driver which implements it. See :ref:`drivers` |
| 293 | for more information. |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 294 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 295 | .. attr:: success |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 296 | |
| 297 | Describes where Zuul should report to if all the jobs complete |
| 298 | successfully. This section is optional; if it is omitted, Zuul |
| 299 | will run jobs and do nothing on success -- it will not report at |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 300 | all. If the section is present, the listed :term:`reporters |
| 301 | <reporter>` will be asked to report on the jobs. The reporters |
| 302 | are listed by their connection name. The options available |
| 303 | depend on the driver for the supplied connection. |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 304 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 305 | .. attr:: failure |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 306 | |
| 307 | These reporters describe what Zuul should do if at least one job |
| 308 | fails. |
| 309 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 310 | .. attr:: merge-failure |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 311 | |
| 312 | These reporters describe what Zuul should do if it is unable to |
| 313 | merge in the patchset. If no merge-failure reporters are listed |
| 314 | then the ``failure`` reporters will be used to notify of |
| 315 | unsuccessful merges. |
| 316 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 317 | .. attr:: start |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 318 | |
| 319 | These reporters describe what Zuul should do when a change is |
| 320 | added to the pipeline. This can be used, for example, to reset |
| 321 | a previously reported result. |
| 322 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 323 | .. attr:: disabled |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 324 | |
| 325 | These reporters describe what Zuul should do when a pipeline is |
| 326 | disabled. See ``disable-after-consecutive-failures``. |
| 327 | |
| 328 | The following options can be used to alter Zuul's behavior to |
| 329 | mitigate situations in which jobs are failing frequently (perhaps |
| 330 | due to a problem with an external dependency, or unusually high |
| 331 | non-deterministic test failures). |
| 332 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 333 | .. attr:: disable-after-consecutive-failures |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 334 | |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 335 | If set, a pipeline can enter a *disabled* state if too many |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 336 | changes in a row fail. When this value is exceeded the pipeline |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 337 | will stop reporting to any of the **success**, **failure** or |
| 338 | **merge-failure** reporters and instead only report to the |
| 339 | **disabled** reporters. (No **start** reports are made when a |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 340 | pipeline is disabled). |
| 341 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 342 | .. attr:: window |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 343 | |
| 344 | Dependent pipeline managers only. Zuul can rate limit dependent |
| 345 | pipelines in a manner similar to TCP flow control. Jobs are |
| 346 | only started for items in the queue if they are within the |
| 347 | actionable window for the pipeline. The initial length of this |
| 348 | window is configurable with this value. The value given should |
| 349 | be a positive integer value. A value of ``0`` disables rate |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 350 | limiting on the :value:`dependent pipeline manager |
| 351 | <pipeline.manager.dependent>`. Default: ``20``. |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 352 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 353 | .. attr:: window-floor |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 354 | |
| 355 | Dependent pipeline managers only. This is the minimum value for |
| 356 | the window described above. Should be a positive non zero |
| 357 | integer value. Default: ``3``. |
| 358 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 359 | .. attr:: window-increase-type |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 360 | |
| 361 | Dependent pipeline managers only. This value describes how the |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 362 | window should grow when changes are successfully merged by zuul. |
| 363 | |
| 364 | .. value:: linear |
| 365 | |
| 366 | Indicates that **window-increase-factor** should be added to |
| 367 | the previous window value. This is the default. |
| 368 | |
| 369 | .. value:: exponential |
| 370 | |
| 371 | Indicates that **window-increase-factor** should be |
| 372 | multiplied against the previous window value and the result |
| 373 | will become the window size. |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 374 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 375 | .. attr:: window-increase-factor |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 376 | |
| 377 | Dependent pipeline managers only. The value to be added or |
| 378 | multiplied against the previous window value to determine the |
| 379 | new window after successful change merges. Default: ``1``. |
| 380 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 381 | .. attr:: window-decrease-type |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 382 | |
| 383 | Dependent pipeline managers only. This value describes how the |
| 384 | window should shrink when changes are not able to be merged by |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 385 | Zuul. |
| 386 | |
| 387 | .. value:: linear |
| 388 | |
| 389 | Indicates that **window-decrease-factor** should be |
| 390 | subtracted from the previous window value. |
| 391 | |
| 392 | .. value:: exponential |
| 393 | |
| 394 | Indicates that **window-decrease-factor** should be divided |
| 395 | against the previous window value and the result will become |
| 396 | the window size. This is the default. |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 397 | |
James E. Blair | 9437591 | 2017-07-28 17:20:27 -0700 | [diff] [blame] | 398 | .. attr:: window-decrease-factor |
James E. Blair | 9fd98ab | 2017-07-26 14:15:26 -0700 | [diff] [blame] | 399 | |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 400 | :value:`Dependent pipeline managers |
| 401 | <pipeline.manager.dependent>` only. The value to be subtracted |
| 402 | or divided against the previous window value to determine the |
| 403 | new window after unsuccessful change merges. Default: ``2``. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 404 | |
| 405 | |
| 406 | .. _job: |
| 407 | |
| 408 | Job |
| 409 | ~~~ |
| 410 | |
| 411 | A job is a unit of work performed by Zuul on an item enqueued into a |
| 412 | pipeline. Items may run any number of jobs (which may depend on each |
| 413 | other). Each job is an invocation of an Ansible playbook with a |
| 414 | specific inventory of hosts. The actual tasks that are run by the job |
| 415 | appear in the playbook for that job while the attributes that appear in the |
| 416 | Zuul configuration specify information about when, where, and how the |
| 417 | job should be run. |
| 418 | |
| 419 | Jobs in Zuul support inheritance. Any job may specify a single parent |
| 420 | job, and any attributes not set on the child job are collected from |
| 421 | the parent job. In this way, a configuration structure may be built |
| 422 | starting with very basic jobs which describe characteristics that all |
| 423 | jobs on the system should have, progressing through stages of |
| 424 | specialization before arriving at a particular job. A job may inherit |
| 425 | from any other job in any project (however, if the other job is marked |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 426 | as ``final``, some attributes may not be overidden). |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 427 | |
| 428 | Jobs also support a concept called variance. The first time a job |
| 429 | definition appears is called the reference definition of the job. |
| 430 | Subsequent job definitions with the same name are called variants. |
| 431 | These may have different selection criteria which indicate to Zuul |
| 432 | that, for instance, the job should behave differently on a different |
| 433 | git branch. Unlike inheritance, all job variants must be defined in |
| 434 | the same project. |
| 435 | |
| 436 | When Zuul decides to run a job, it performs a process known as |
| 437 | freezing the job. Because any number of job variants may be |
| 438 | applicable, Zuul collects all of the matching variants and applies |
| 439 | them in the order they appeared in the configuration. The resulting |
| 440 | frozen job is built from attributes gathered from all of the |
| 441 | matching variants. In this way, exactly what is run is dependent on |
| 442 | the pipeline, project, branch, and content of the item. |
| 443 | |
| 444 | In addition to the job's main playbook, each job may specify one or |
| 445 | more pre- and post-playbooks. These are run, in order, before and |
| 446 | after (respectively) the main playbook. They may be used to set up |
| 447 | and tear down resources needed by the main playbook. When combined |
| 448 | with inheritance, they provide powerful tools for job construction. A |
| 449 | job only has a single main playbook, and when inheriting from a |
| 450 | parent, the child's main playbook overrides (or replaces) the |
| 451 | parent's. However, the pre- and post-playbooks are appended and |
| 452 | prepended in a nesting fashion. So if a parent job and child job both |
| 453 | specified pre and post playbooks, the sequence of playbooks run would |
| 454 | be: |
| 455 | |
| 456 | * parent pre-run playbook |
| 457 | * child pre-run playbook |
| 458 | * child playbook |
| 459 | * child post-run playbook |
| 460 | * parent post-run playbook |
| 461 | |
| 462 | Further inheritance would nest even deeper. |
| 463 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 464 | Here is an example of two job definitions: |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 465 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 466 | .. code-block:: yaml |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 467 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 468 | - job: |
| 469 | name: base |
| 470 | pre-run: copy-git-repos |
| 471 | post-run: copy-logs |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 472 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 473 | - job: |
| 474 | name: run-tests |
| 475 | parent: base |
| 476 | nodes: |
| 477 | - name: test-node |
| 478 | image: fedora |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 479 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 480 | .. attr:: job |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 481 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 482 | The following attributes are available on a job; all are optional |
| 483 | unless otherwise specified: |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 484 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 485 | .. attr:: name |
| 486 | :required: |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 487 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 488 | The name of the job. By default, Zuul looks for a playbook with |
| 489 | this name to use as the main playbook for the job. This name is |
| 490 | also referenced later in a project pipeline configuration. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 491 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 492 | .. attr:: parent |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 493 | |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 494 | Specifies a job to inherit from. The parent job can be defined |
| 495 | in this or any other project. Any attributes not specified on |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 496 | a job will be collected from its parent. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 497 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 498 | .. attr:: description |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 499 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 500 | A textual description of the job. Not currently used directly |
| 501 | by Zuul, but it is used by the zuul-sphinx extension to Sphinx |
| 502 | to auto-document Zuul jobs (in which case it is interpreted as |
| 503 | ReStructuredText. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 504 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 505 | .. attr:: success-message |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 506 | |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 507 | Normally when a job succeeds, the string ``SUCCESS`` is reported |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 508 | as the result for the job. If set, this option may be used to |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 509 | supply a different string. Default: ``SUCCESS``. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 510 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 511 | .. attr:: failure-message |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 512 | |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 513 | Normally when a job fails, the string ``FAILURE`` is reported as |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 514 | the result for the job. If set, this option may be used to |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 515 | supply a different string. Default: ``FAILURE``. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 516 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 517 | .. attr:: success-url |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 518 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 519 | When a job succeeds, this URL is reported along with the result. |
| 520 | If this value is not supplied, Zuul uses the content of the job |
| 521 | :ref:`return value <return_values>` **zuul.log_url**. This is |
| 522 | recommended as it allows the code which stores the URL to the |
| 523 | job artifacts to report exactly where they were stored. To |
| 524 | override this value, or if it is not set, supply an absolute URL |
| 525 | in this field. If a relative URL is supplied in this field, and |
| 526 | **zuul.log_url** is set, then the two will be combined to |
| 527 | produce the URL used for the report. This can be used to |
| 528 | specify that certain jobs should "deep link" into the stored job |
| 529 | artifacts. Default: none. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 530 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 531 | .. attr:: failure-url |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 532 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 533 | When a job fails, this URL is reported along with the result. |
| 534 | Otherwise behaves the same as **success-url**. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 535 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 536 | .. attr:: hold-following-changes |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 537 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 538 | In a dependent pipeline, this option may be used to indicate |
| 539 | that no jobs should start on any items which depend on the |
| 540 | current item until this job has completed successfully. This |
| 541 | may be used to conserve build resources, at the expense of |
| 542 | inhibiting the parallelization which speeds the processing of |
| 543 | items in a dependent pipeline. A boolean value, default: false. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 544 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 545 | .. attr:: voting |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 546 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 547 | Indicates whether the result of this job should be used in |
| 548 | determining the overall result of the item. A boolean value, |
| 549 | default: true. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 550 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 551 | .. attr:: semaphore |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 552 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 553 | The name of a :ref:`semaphore` which should be acquired and |
| 554 | released when the job begins and ends. If the semaphore is at |
| 555 | maximum capacity, then Zuul will wait until it can be acquired |
| 556 | before starting the job. Default: none. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 557 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 558 | .. attr:: tags |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 559 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 560 | Metadata about this job. Tags are units of information attached |
| 561 | to the job; they do not affect Zuul's behavior, but they can be |
| 562 | used within the job to characterize the job. For example, a job |
| 563 | which tests a certain subsystem could be tagged with the name of |
| 564 | that subsystem, and if the job's results are reported into a |
| 565 | database, then the results of all jobs affecting that subsystem |
| 566 | could be queried. This attribute is specified as a list of |
| 567 | strings, and when inheriting jobs or applying variants, tags |
| 568 | accumulate in a set, so the result is always a set of all the |
| 569 | tags from all the jobs and variants used in constructing the |
| 570 | frozen job, with no duplication. Default: none. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 571 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 572 | .. attr:: branches |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 573 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 574 | A regular expression (or list of regular expressions) which |
| 575 | describe on what branches a job should run (or in the case of |
| 576 | variants: to alter the behavior of a job for a certain branch). |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 577 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 578 | If there is no job definition for a given job which matches the |
| 579 | branch of an item, then that job is not run for the item. |
| 580 | Otherwise, all of the job variants which match that branch (and |
| 581 | any other selection criteria) are used when freezing the job. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 582 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 583 | This example illustrates a job called *run-tests* which uses a |
| 584 | nodeset based on the current release of an operating system to |
| 585 | perform its tests, except when testing changes to the stable/2.0 |
| 586 | branch, in which case it uses an older release: |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 587 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 588 | .. code-block:: yaml |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 589 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 590 | - job: |
| 591 | name: run-tests |
| 592 | nodes: current-release |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 593 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 594 | - job: |
| 595 | name: run-tests |
| 596 | branch: stable/2.0 |
| 597 | nodes: old-release |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 598 | |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 599 | In some cases, Zuul uses an implied value for the branch |
| 600 | specifier if none is supplied: |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 601 | |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 602 | * For a job definition in a :term:`config-project`, no implied |
| 603 | branch specifier is used. If no branch specifier appears, the |
| 604 | job applies to all branches. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 605 | |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 606 | * In the case of an :term:`untrusted-project`, no implied branch |
| 607 | specifier is applied to the reference definition of a job. |
| 608 | That is to say, that if the first appearance of the job |
| 609 | definition appears without a branch specifier, then it will |
| 610 | apply to all branches. Note that when collecting its |
| 611 | configuration, Zuul reads the ``master`` branch of a given |
| 612 | project first, then other branches in alphabetical order. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 613 | |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 614 | * Any further job variants other than the reference definition |
| 615 | in an untrusted-project will, if they do not have a branch |
| 616 | specifier, will have an implied branch specifier for the |
| 617 | current branch applied. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 618 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 619 | This allows for the very simple and expected workflow where if a |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 620 | project defines a job on the ``master`` branch with no branch |
| 621 | specifier, and then creates a new branch based on ``master``, |
| 622 | any changes to that job definition within the new branch only |
| 623 | affect that branch. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 624 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 625 | .. attr:: files |
Tobias Henkel | 2aade26 | 2017-07-12 16:09:06 +0200 | [diff] [blame] | 626 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 627 | This attribute indicates that the job should only run on changes |
| 628 | where the specified files are modified. This is a regular |
| 629 | expression or list of regular expressions. Default: none. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 630 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 631 | .. attr:: irrelevant-files |
James E. Blair | 74a82cf | 2017-07-12 17:23:08 -0700 | [diff] [blame] | 632 | |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 633 | This is a negative complement of **files**. It indicates that |
| 634 | the job should run unless *all* of the files changed match this |
| 635 | list. In other words, if the regular expression ``docs/.*`` is |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 636 | supplied, then this job will not run if the only files changed |
| 637 | are in the docs directory. A regular expression or list of |
| 638 | regular expressions. Default: none. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 639 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 640 | .. attr:: auth |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 641 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 642 | Authentication information to be made available to the job. |
| 643 | This is a dictionary with two potential keys: |
James E. Blair | bb94dfa | 2017-07-11 07:45:19 -0700 | [diff] [blame] | 644 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 645 | .. attr:: inherit |
James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 646 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 647 | A boolean indicating that the authentication information |
| 648 | referenced by this job should be able to be inherited by |
| 649 | child jobs. Normally when a job inherits from another job, |
| 650 | the auth section is not included. This permits jobs to |
| 651 | inherit the same basic structure and playbook, but ensures |
| 652 | that secret information is unable to be exposed by a child |
| 653 | job which may alter the job's behavior. If it is safe for |
| 654 | the contents of the authentication section to be used by |
| 655 | child jobs, set this to ``true``. Default: ``false``. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 656 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 657 | .. attr:: secrets |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 658 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 659 | A list of secrets which may be used by the job. A |
| 660 | :ref:`secret` is a named collection of private information |
| 661 | defined separately in the configuration. The secrets that |
| 662 | appear here must be defined in the same project as this job |
| 663 | definition. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 664 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 665 | In the future, other types of authentication information may |
| 666 | be added. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 667 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 668 | .. attr:: nodes |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 669 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 670 | A list of nodes which should be supplied to the job. This |
| 671 | parameter may be supplied either as a string, in which case it |
| 672 | references a :ref:`nodeset` definition which appears elsewhere |
| 673 | in the configuration, or a list, in which case it is interpreted |
| 674 | in the same way as a Nodeset definition (in essence, it is an |
| 675 | anonymous Node definition unique to this job). See the |
| 676 | :ref:`nodeset` reference for the syntax to use in that case. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 677 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 678 | If a job has an empty or no node definition, it will still run |
| 679 | and may be able to perform actions on the Zuul executor. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 680 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 681 | .. attr:: override-branch |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 682 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 683 | When Zuul runs jobs for a proposed change, it normally checks |
| 684 | out the branch associated with that change on every project |
| 685 | present in the job. If jobs are running on a ref (such as a |
| 686 | branch tip or tag), then that ref is normally checked out. This |
| 687 | attribute is used to override that behavior and indicate that |
| 688 | this job should, regardless of the branch for the queue item, |
| 689 | use the indicated branch instead. This can be used, for |
| 690 | example, to run a previous version of the software (from a |
| 691 | stable maintenance branch) under test even if the change being |
| 692 | tested applies to a different branch (this is only likely to be |
| 693 | useful if there is some cross-branch interaction with some |
| 694 | component of the system being tested). See also the |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 695 | project-specific :attr:`job.required-projects.override-branch` |
| 696 | attribute to apply this behavior to a subset of a job's |
| 697 | projects. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 698 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 699 | .. attr:: timeout |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 700 | |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 701 | The time in minutes that the job should be allowed to run before |
| 702 | it is automatically aborted and failure is reported. If no |
| 703 | timeout is supplied, the job may run indefinitely. Supplying a |
| 704 | timeout is highly recommended. |
| 705 | |
| 706 | .. attr:: attempts |
| 707 | |
| 708 | When Zuul encounters an error running a job's pre-run playbook, |
| 709 | Zuul will stop and restart the job. Errors during the main or |
| 710 | post-run -playbook phase of a job are not affected by this |
| 711 | parameter (they are reported immediately). This parameter |
| 712 | controls the number of attempts to make before an error is |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 713 | reported. Default: ``3``. |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 714 | |
| 715 | .. attr:: pre-run |
| 716 | |
| 717 | The name of a playbook or list of playbooks without file |
| 718 | extension to run before the main body of a job. The full path |
| 719 | to the playbook in the repo where the job is defined is |
| 720 | expected. |
| 721 | |
| 722 | When a job inherits from a parent, the child's pre-run playbooks |
| 723 | are run after the parent's. See :ref:`job` for more |
| 724 | information. |
| 725 | |
| 726 | .. attr:: post-run |
| 727 | |
| 728 | The name of a playbook or list of playbooks without file |
| 729 | extension to run after the main body of a job. The full path to |
| 730 | the playbook in the repo where the job is defined is expected. |
| 731 | |
| 732 | When a job inherits from a parent, the child's post-run |
| 733 | playbooks are run before the parent's. See :ref:`job` for more |
| 734 | information. |
| 735 | |
| 736 | .. attr:: run |
| 737 | |
| 738 | The name of the main playbook for this job. This parameter is |
| 739 | not normally necessary, as it defaults to a playbook with the |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 740 | same name as the job inside of the ``playbooks/`` directory |
| 741 | (e.g., the ``foo`` job would default to ``playbooks/foo``. |
| 742 | However, if a playbook with a different name is needed, it can |
| 743 | be specified here. The file extension is not required, but the |
| 744 | full path within the repo is. When a child inherits from a |
| 745 | parent, a playbook with the name of the child job is implicitly |
| 746 | searched first, before falling back on the playbook used by the |
| 747 | parent job (unless the child job specifies a ``run`` attribute, |
| 748 | in which case that value is used). Example: |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 749 | |
| 750 | .. code-block:: yaml |
| 751 | |
| 752 | run: playbooks/<name of the job> |
| 753 | |
| 754 | .. attr:: roles |
| 755 | |
| 756 | A list of Ansible roles to prepare for the job. Because a job |
| 757 | runs an Ansible playbook, any roles which are used by the job |
| 758 | must be prepared and installed by Zuul before the job begins. |
| 759 | This value is a list of dictionaries, each of which indicates |
| 760 | one of two types of roles: a Galaxy role, which is simply a role |
| 761 | that is installed from Ansible Galaxy, or a Zuul role, which is |
| 762 | a role provided by a project managed by Zuul. Zuul roles are |
| 763 | able to benefit from speculative merging and cross-project |
| 764 | dependencies when used by playbooks in untrusted projects. |
| 765 | Roles are added to the Ansible role path in the order they |
| 766 | appear on the job -- roles earlier in the list will take |
| 767 | precedence over those which follow. |
| 768 | |
| 769 | In the case of job inheritance or variance, the roles used for |
| 770 | each of the playbooks run by the job will be only those which |
| 771 | were defined along with that playbook. If a child job inherits |
| 772 | from a parent which defines a pre and post playbook, then the |
| 773 | pre and post playbooks it inherits from the parent job will run |
| 774 | only with the roles that were defined on the parent. If the |
| 775 | child adds its own pre and post playbooks, then any roles added |
| 776 | by the child will be available to the child's playbooks. This |
| 777 | is so that a job which inherits from a parent does not |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 778 | inadvertently alter the behavior of the parent's playbooks by |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 779 | the addition of conflicting roles. Roles added by a child will |
| 780 | appear before those it inherits from its parent. |
| 781 | |
| 782 | A project which supplies a role may be structured in one of two |
| 783 | configurations: a bare role (in which the role exists at the |
| 784 | root of the project), or a contained role (in which the role |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 785 | exists within the ``roles/`` directory of the project, perhaps |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 786 | along with other roles). In the case of a contained role, the |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 787 | ``roles/`` directory of the project is added to the role search |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 788 | path. In the case of a bare role, the project itself is added |
| 789 | to the role search path. In case the name of the project is not |
| 790 | the name under which the role should be installed (and therefore |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 791 | referenced from Ansible), the ``name`` attribute may be used to |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 792 | specify an alternate. |
| 793 | |
| 794 | A job automatically has the project in which it is defined added |
| 795 | to the roles path if that project appears to contain a role or |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 796 | ``roles/`` directory. By default, the project is added to the |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 797 | path under its own name, however, that may be changed by |
| 798 | explicitly listing the project in the roles list in the usual |
| 799 | way. |
| 800 | |
| 801 | .. note:: Galaxy roles are not yet implemented. |
| 802 | |
| 803 | .. attr:: galaxy |
| 804 | |
| 805 | The name of the role in Ansible Galaxy. If this attribute is |
| 806 | supplied, Zuul will search Ansible Galaxy for a role by this |
| 807 | name and install it. Mutually exclusive with ``zuul``; |
| 808 | either ``galaxy`` or ``zuul`` must be supplied. |
| 809 | |
| 810 | .. attr:: zuul |
| 811 | |
| 812 | The name of a Zuul project which supplies the role. Mutually |
| 813 | exclusive with ``galaxy``; either ``galaxy`` or ``zuul`` must |
| 814 | be supplied. |
| 815 | |
| 816 | .. attr:: name |
| 817 | |
| 818 | The installation name of the role. In the case of a bare |
| 819 | role, the role will be made available under this name. |
| 820 | Ignored in the case of a contained role. |
| 821 | |
| 822 | .. attr:: required-projects |
| 823 | |
| 824 | A list of other projects which are used by this job. Any Zuul |
| 825 | projects specified here will also be checked out by Zuul into |
| 826 | the working directory for the job. Speculative merging and |
| 827 | cross-repo dependencies will be honored. |
| 828 | |
| 829 | The format for this attribute is either a list of strings or |
| 830 | dictionaries. Strings are interpreted as project names, |
| 831 | dictionaries, if used, may have the following attributes: |
| 832 | |
| 833 | .. attr:: name |
| 834 | :required: |
| 835 | |
| 836 | The name of the required project. |
| 837 | |
| 838 | .. attr:: override-branch |
| 839 | |
| 840 | When Zuul runs jobs for a proposed change, it normally checks |
| 841 | out the branch associated with that change on every project |
| 842 | present in the job. If jobs are running on a ref (such as a |
| 843 | branch tip or tag), then that ref is normally checked out. |
| 844 | This attribute is used to override that behavior and indicate |
| 845 | that this job should, regardless of the branch for the queue |
| 846 | item, use the indicated branch instead, for only this |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 847 | project. See also the :attr:`job.override-branch` attribute |
James E. Blair | 32c5248 | 2017-07-29 07:49:03 -0700 | [diff] [blame] | 848 | to apply the same behavior to all projects in a job. |
| 849 | |
| 850 | .. attr:: vars |
| 851 | |
| 852 | A dictionary of variables to supply to Ansible. When inheriting |
| 853 | from a job (or creating a variant of a job) vars are merged with |
| 854 | previous definitions. This means a variable definition with the |
| 855 | same name will override a previously defined variable, but new |
| 856 | variable names will be added to the set of defined variables. |
| 857 | |
| 858 | .. attr:: dependencies |
| 859 | |
| 860 | A list of other jobs upon which this job depends. Zuul will not |
| 861 | start executing this job until all of its dependencies have |
| 862 | completed successfully, and if one or more of them fail, this |
| 863 | job will not be run. |
| 864 | |
| 865 | .. attr:: allowed-projects |
| 866 | |
| 867 | A list of Zuul projects which may use this job. By default, a |
| 868 | job may be used by any other project known to Zuul, however, |
| 869 | some jobs use resources or perform actions which are not |
| 870 | appropriate for other projects. In these cases, a list of |
| 871 | projects which are allowed to use this job may be supplied. If |
| 872 | this list is not empty, then it must be an exhaustive list of |
| 873 | all projects permitted to use the job. The current project |
| 874 | (where the job is defined) is not automatically included, so if |
| 875 | it should be able to run this job, then it must be explicitly |
| 876 | listed. Default: the empty list (all projects may use the job). |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 877 | |
| 878 | |
| 879 | .. _project: |
| 880 | |
| 881 | Project |
| 882 | ~~~~~~~ |
| 883 | |
| 884 | A project corresponds to a source code repository with which Zuul is |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 885 | configured to interact. The main responsibility of the project |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 886 | configuration item is to specify which jobs should run in which |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 887 | pipelines for a given project. Within each project definition, a |
| 888 | section for each :ref:`pipeline <pipeline>` may appear. This |
| 889 | project-pipeline definition is what determines how a project |
| 890 | participates in a pipeline. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 891 | |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 892 | Consider the following project definition:: |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 893 | |
| 894 | - project: |
| 895 | name: yoyodyne |
| 896 | check: |
| 897 | jobs: |
| 898 | - check-syntax |
| 899 | - unit-tests |
| 900 | gate: |
| 901 | queue: integrated |
| 902 | jobs: |
| 903 | - unit-tests |
| 904 | - integration-tests |
| 905 | |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 906 | The project has two project-pipeline stanzas, one for the ``check`` |
| 907 | pipeline, and one for ``gate``. Each specifies which jobs should run |
| 908 | when a change for that project enters the respective pipeline -- when |
| 909 | a change enters ``check``, the ``check-syntax`` and ``unit-test`` jobs |
| 910 | are run. |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 911 | |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 912 | Pipelines which use the dependent pipeline manager (e.g., the ``gate`` |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 913 | example shown earlier) maintain separate queues for groups of |
| 914 | projects. When Zuul serializes a set of changes which represent |
| 915 | future potential project states, it must know about all of the |
| 916 | projects within Zuul which may have an effect on the outcome of the |
| 917 | jobs it runs. If project *A* uses project *B* as a library, then Zuul |
| 918 | must be told about that relationship so that it knows to serialize |
| 919 | changes to A and B together, so that it does not merge a change to B |
| 920 | while it is testing a change to A. |
| 921 | |
| 922 | Zuul could simply assume that all projects are related, or even infer |
| 923 | relationships by which projects a job indicates it uses, however, in a |
| 924 | large system that would become unwieldy very quickly, and |
| 925 | unnecessarily delay changes to unrelated projects. To allow for |
| 926 | flexibility in the construction of groups of related projects, the |
| 927 | change queues used by dependent pipeline managers are specified |
| 928 | manually. To group two or more related projects into a shared queue |
| 929 | for a dependent pipeline, set the ``queue`` parameter to the same |
| 930 | value for those projects. |
| 931 | |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 932 | The ``gate`` project-pipeline definition above specifies that this |
| 933 | project participates in the ``integrated`` shared queue for that |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 934 | pipeline. |
| 935 | |
| 936 | In addition to a project-pipeline definition for one or more |
James E. Blair | ac3c7ae | 2017-07-31 09:01:08 -0700 | [diff] [blame^] | 937 | pipelines, the following attributes may appear in a project: |
James E. Blair | 1de8d40 | 2017-05-07 17:08:04 -0700 | [diff] [blame] | 938 | |
| 939 | **name** (required) |
| 940 | The name of the project. If Zuul is configured with two or more |
| 941 | unique projects with the same name, the canonical hostname for the |
| 942 | project should be included (e.g., `git.example.com/foo`). |
| 943 | |
| 944 | **templates** |
| 945 | A list of :ref:`project-template` references; the project-pipeline |
| 946 | definitions of each Project Template will be applied to this |
| 947 | project. If more than one template includes jobs for a given |
| 948 | pipeline, they will be combined, as will any jobs specified in |
| 949 | project-pipeline definitions on the project itself. |
| 950 | |
| 951 | .. _project-template: |
| 952 | |
| 953 | Project Template |
| 954 | ~~~~~~~~~~~~~~~~ |
| 955 | |
| 956 | A Project Template defines one or more project-pipeline definitions |
| 957 | which can be re-used by multiple projects. |
| 958 | |
| 959 | A Project Template uses the same syntax as a :ref:`project` |
| 960 | definition, however, in the case of a template, the ``name`` attribute |
| 961 | does not refer to the name of a project, but rather names the template |
| 962 | so that it can be referenced in a `Project` definition. |
| 963 | |
| 964 | .. _secret: |
| 965 | |
| 966 | Secret |
| 967 | ~~~~~~ |
| 968 | |
| 969 | A Secret is a collection of private data for use by one or more jobs. |
| 970 | In order to maintain the security of the data, the values are usually |
| 971 | encrypted, however, data which are not sensitive may be provided |
| 972 | unencrypted as well for convenience. |
| 973 | |
| 974 | A Secret may only be used by jobs defined within the same project. To |
| 975 | use a secret, a :ref:`job` must specify the secret within its `auth` |
| 976 | section. To protect against jobs in other repositories declaring a |
| 977 | job with a secret as a parent and then exposing that secret, jobs |
| 978 | which inherit from a job with secrets will not inherit the secrets |
| 979 | themselves. To alter that behavior, see the `inherit` job attribute. |
| 980 | Further, jobs which do not permit children to inherit secrets (the |
| 981 | default) are also automatically marked `final`, meaning that their |
| 982 | execution related attributes may not be changed in a project-pipeline |
| 983 | stanza. This is to protect against a job with secrets defined in one |
| 984 | project being used by another project in a way which might expose the |
| 985 | secrets. If a job with secrets is unsafe to be used by other |
| 986 | projects, the `allowed-projects` job attribute can be used to restrict |
| 987 | the projects which can invoke that job. Finally, pipelines which are |
| 988 | used to execute proposed but unreviewed changes can set the |
| 989 | `allow-secrets` attribute to indicate that they should not supply |
| 990 | secrets at all in order to protect against someone proposing a change |
| 991 | which exposes a secret. |
| 992 | |
| 993 | The following attributes are required: |
| 994 | |
| 995 | **name** (required) |
| 996 | The name of the secret, used in a :ref:`Job` definition to request |
| 997 | the secret. |
| 998 | |
| 999 | **data** (required) |
| 1000 | A dictionary which will be added to the Ansible variables available |
| 1001 | to the job. The values can either be plain text strings, or |
| 1002 | encrypted values. See :ref:`encryption` for more information. |
| 1003 | |
| 1004 | .. _nodeset: |
| 1005 | |
| 1006 | Nodeset |
| 1007 | ~~~~~~~ |
| 1008 | |
| 1009 | A Nodeset is a named collection of nodes for use by a job. Jobs may |
| 1010 | specify what nodes they require individually, however, by defining |
| 1011 | groups of node types once and referring to them by name, job |
| 1012 | configuration may be simplified. |
| 1013 | |
| 1014 | A Nodeset requires two attributes: |
| 1015 | |
| 1016 | **name** (required) |
| 1017 | The name of the Nodeset, to be referenced by a :ref:`job`. |
| 1018 | |
| 1019 | **nodes** (required) |
| 1020 | A list of node definitions, each of which has the following format: |
| 1021 | |
| 1022 | **name** (required) |
| 1023 | The name of the node. This will appear in the Ansible inventory |
| 1024 | for the job. |
| 1025 | |
| 1026 | **label** (required) |
| 1027 | The Nodepool label for the node. Zuul will request a node with |
| 1028 | this label. |
| 1029 | |
| 1030 | .. _semaphore: |
| 1031 | |
| 1032 | Semaphore |
| 1033 | ~~~~~~~~~ |
| 1034 | |
| 1035 | Semaphores can be used to restrict the number of certain jobs which |
| 1036 | are running at the same time. This may be useful for jobs which |
| 1037 | access shared or limited resources. A semaphore has a value which |
| 1038 | represents the maximum number of jobs which use that semaphore at the |
| 1039 | same time. |
| 1040 | |
| 1041 | Semaphores are never subject to dynamic reconfiguration. If the value |
| 1042 | of a semaphore is changed, it will take effect only when the change |
| 1043 | where it is updated is merged. An example follows:: |
| 1044 | |
| 1045 | - semaphore: |
| 1046 | name: semaphore-foo |
| 1047 | max: 5 |
| 1048 | - semaphore: |
| 1049 | name: semaphore-bar |
| 1050 | max: 3 |
| 1051 | |
| 1052 | The following attributes are available: |
| 1053 | |
| 1054 | **name** (required) |
| 1055 | The name of the semaphore, referenced by jobs. |
| 1056 | |
| 1057 | **max** |
| 1058 | The maximum number of running jobs which can use this semaphore. |
| 1059 | Defaults to 1. |