Debian Codegraph @

jenkins_jobs/modules/properties.py

raw
1 # Copyright 2012 Hewlett-Packard Development Company, L.P.
2 # Copyright 2020 Liberty Global B.V.
3 #
4 # Licensed under the Apache License, Version 2.0 (the "License");
5 # you may not use this file except in compliance with the License.
6 # You may obtain a copy of the License at
7 #
8 # http://www.apache.org/licenses/LICENSE-2.0
9 #
10 # Unless required by applicable law or agreed to in writing, software
11 # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12 # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 # License for the specific language governing permissions and limitations
14 # under the License.
15
16
17 """
18 The Properties module supplies a wide range of options that are
19 implemented as Jenkins job properties.
20
21 **Component**: properties
22 :Macro: property
23 :Entry Point: jenkins_jobs.properties
24
25 Example::
26
27 job:
28 name: test_job
29
30 properties:
31 - github:
32 url: https://github.com/openstack-infra/jenkins-job-builder/
33 """
34
35 import logging
36 import xml.etree.ElementTree as XML
37
38 from jenkins_jobs.errors import InvalidAttributeError
39 from jenkins_jobs.errors import JenkinsJobsException
40 from jenkins_jobs.errors import MissingAttributeError
41 from jenkins_jobs.errors import AttributeConflictError
42 import jenkins_jobs.modules.base
43 import jenkins_jobs.modules.helpers as helpers
44
45
46 def builds_chain_fingerprinter(registry, xml_parent, data):
47 """yaml: builds-chain-fingerprinter
48 Builds chain fingerprinter.
49
50 Requires the Jenkins :jenkins-github:`Builds chain fingerprinter Plugin
51 <builds-chain-fingerprinter-plugin>`.
52
53 :arg bool per-builds-chain: enable builds hierarchy fingerprinting
54 (default false)
55 :arg bool per-job-chain: enable jobs hierarchy fingerprinting
56 (default false)
57
58 Example:
59
60 .. literalinclude:: /../../tests/properties/fixtures/fingerprinter.yaml
61 :language: yaml
62 """
63 fingerprinter = XML.SubElement(
64 xml_parent,
65 "org.jenkinsci.plugins."
66 "buildschainfingerprinter."
67 "AutomaticFingerprintJobProperty",
68 )
69 mapping = [
70 ("per-builds-chain", "isPerBuildsChainEnabled", False),
71 ("per-job-chain", "isPerJobsChainEnabled", False),
72 ]
73 helpers.convert_mapping_to_xml(fingerprinter, data, mapping, fail_required=True)
74
75
76 def ownership(registry, xml_parent, data):
77 """yaml: ownership
78 Plugin provides explicit ownership for jobs and slave nodes.
79
80 Requires the Jenkins :jenkins-plugins:`Ownership Plugin <ownership>`.
81
82 :arg bool enabled: whether ownership enabled (default : true)
83 :arg str owner: the owner of job
84 :arg list co-owners: list of job co-owners
85
86 Example:
87
88 .. literalinclude:: /../../tests/properties/fixtures/ownership.yaml
89 :language: yaml
90 """
91 ownership_plugin = XML.SubElement(
92 xml_parent,
93 "com.synopsys.arc.jenkins.plugins.ownership.jobs.JobOwnerJobProperty",
94 )
95 ownership = XML.SubElement(ownership_plugin, "ownership")
96 owner = str(data.get("enabled", True)).lower()
97 XML.SubElement(ownership, "ownershipEnabled").text = owner
98
99 XML.SubElement(ownership, "primaryOwnerId").text = data.get("owner")
100
101 coownersIds = XML.SubElement(ownership, "coownersIds")
102 for coowner in data.get("co-owners", []):
103 XML.SubElement(coownersIds, "string").text = coowner
104
105
106 def promoted_build(registry, xml_parent, data):
107 """yaml: promoted-build
108 Marks a build for promotion. A promotion process with an identical
109 name must be created via the web interface in the job in order for the job
110 promotion to persist. Promotion processes themselves cannot be configured
111 by jenkins-jobs due to the separate storage of plugin configuration files.
112
113 Requires the Jenkins :jenkins-plugins:`Promoted Builds Plugin
114 <promoted-builds>`.
115
116 :arg list names: the promoted build names (optional)
117
118 Example:
119
120 .. literalinclude:: /../../tests/properties/fixtures/promoted_build.yaml
121 :language: yaml
122 """
123 promoted = XML.SubElement(
124 xml_parent, "hudson.plugins.promoted__builds." "JobPropertyImpl"
125 )
126 names = data.get("names", [])
127 if names:
128 active_processes = XML.SubElement(promoted, "activeProcessNames")
129 for n in names:
130 XML.SubElement(active_processes, "string").text = str(n)
131
132
133 def gitbucket(parser, xml_parent, data):
134 """yaml: gitbucket
135 Integrate GitBucket to Jenkins.
136
137 Requires the Jenkins :jenkins-plugins:`GitBucket Plugin <gitbucket>`.
138
139 :arg str url: GitBucket URL to issue (required)
140 :arg bool link-enabled: Enable hyperlink to issue (default false)
141
142 Minimal Example:
143
144 .. literalinclude:: /../../tests/properties/fixtures/gitbucket-minimal.yaml
145 :language: yaml
146
147 Full Example:
148
149 .. literalinclude:: /../../tests/properties/fixtures/gitbucket-full.yaml
150 :language: yaml
151 """
152 gitbucket = XML.SubElement(
153 xml_parent, "org.jenkinsci.plugins.gitbucket.GitBucketProjectProperty"
154 )
155 gitbucket.set("plugin", "gitbucket")
156
157 mapping = [("url", "url", None), ("link-enabled", "linkEnabled", False)]
158 helpers.convert_mapping_to_xml(gitbucket, data, mapping, fail_required=True)
159
160
161 def github(registry, xml_parent, data):
162 """yaml: github
163 Sets the GitHub URL for the project.
164
165 :arg str url: the GitHub URL (required)
166 :arg str display-name: This value will be used as context name for commit
167 status if status builder or status publisher is defined for this
168 project. (>= 1.14.1) (default '')
169
170 Minimal Example:
171
172 .. literalinclude:: /../../tests/properties/fixtures/github-minimal.yaml
173 :language: yaml
174
175 Full Example:
176
177 .. literalinclude:: /../../tests/properties/fixtures/github-full.yaml
178 :language: yaml
179 """
180 github = XML.SubElement(
181 xml_parent, "com.coravy.hudson.plugins.github.GithubProjectProperty"
182 )
183 github.set("plugin", "github")
184
185 mapping = [("url", "projectUrl", None), ("display-name", "displayName", "")]
186 helpers.convert_mapping_to_xml(github, data, mapping, fail_required=True)
187
188
189 def gitlab(registry, xml_parent, data):
190 """yaml: gitlab
191 Sets the GitLab connection for the project. Configured via Jenkins Global
192 Configuration.
193
194 Requires the Jenkins :jenkins-plugins:`GitLab Plugin <gitlab-plugin>`.
195
196 :arg str connection: the GitLab connection name (required)
197
198 Example:
199
200 .. literalinclude:: /../../tests/properties/fixtures/gitlab.yaml
201 :language: yaml
202 """
203 gitlab = XML.SubElement(
204 xml_parent,
205 "com.dabsquared.gitlabjenkins.connection." "GitLabConnectionProperty",
206 )
207 mapping = [("connection", "gitLabConnection", None)]
208 helpers.convert_mapping_to_xml(gitlab, data, mapping, fail_required=True)
209
210
211 def gitlab_logo(registry, xml_parent, data):
212 """yaml: gitlab-logo
213 Configures the GitLab-Logo Plugin.
214
215 Requires the Jenkins :jenkins-plugins:`GitLab Logo Plugin
216 <gitlab-logo>`.
217
218 :arg str repository-name: the GitLab repository name (required)
219
220 Example:
221
222 .. literalinclude:: /../../tests/properties/fixtures/gitlab-logo.yaml
223 :language: yaml
224 """
225 logo = XML.SubElement(
226 xml_parent, "org.jenkinsci.plugins.gitlablogo." "GitlabLogoProperty"
227 )
228 mapping = [("repository-name", "repositoryName", None)]
229 helpers.convert_mapping_to_xml(logo, data, mapping, fail_required=True)
230
231
232 def gogs(registry, xml_parent, data):
233 """yaml: gogs
234 Sets the Gogs webhook properties for the project.
235
236 Requires the Jenkins :jenkins-plugins:`Gogs Plugin <gogs-webhook>`.
237
238 :arg str secret: webhook secret (default '')
239 :arg str branch-filter: filter which needs to match to trigger a job (default '')
240
241 Minimal Example:
242
243 .. literalinclude:: /../../tests/properties/fixtures/gogs-minimal.yaml
244 :language: yaml
245
246 Full Example:
247
248 .. literalinclude:: /../../tests/properties/fixtures/gogs-full.yaml
249 :language: yaml
250 """
251 gogs = XML.SubElement(xml_parent, "org.jenkinsci.plugins.gogs.GogsProjectProperty")
252 mapping = [("branch-filter", "gogsBranchFilter", ""), ("secret", "gogsSecret", "")]
253 helpers.convert_mapping_to_xml(gogs, data, mapping)
254
255
256 def naginator_opt_out(registry, xml_parent, data):
257 """yaml: naginator-opt-out
258 Lets you opt-out so no rebuild option for Naginator is added.
259
260 Requires the Jenkins :jenkins-plugins:`Naginator Plugin <naginator>`.
261
262 :arg bool opt-out: disables the rebuild option if True (default False).
263
264 Example:
265
266 .. literalinclude:: /../../tests/properties/fixtures/naginator-opt-out002.yaml
267 :language: yaml
268 """
269
270 opt_out = XML.SubElement(
271 xml_parent, "com.chikli.hudson.plugin.naginator." "NaginatorOptOutProperty"
272 )
273 mapping = [("opt-out", "optOut", False)]
274 helpers.convert_mapping_to_xml(opt_out, data, mapping, fail_required=True)
275
276
277 def disk_usage(registry, xml_parent, data):
278 """yaml: disk-usage
279 Enables the Disk Usage Plugin.
280
281 Requires the Jenkins :jenkins-plugins:`Disk Usage Plugin <disk-usage>`.
282
283 Example:
284
285 .. literalinclude:: /../../tests/properties/fixtures/disk-usage.yaml
286 :language: yaml
287 """
288 XML.SubElement(xml_parent, "hudson.plugins.disk__usage." "DiskUsageProperty")
289
290
291 def least_load(registry, xml_parent, data):
292 """yaml: least-load
293 Enables the Least Load Plugin.
294
295 Requires the Jenkins :jenkins-plugins:`Least Load Plugin <leastload>`.
296
297 :arg bool disabled: whether or not leastload is disabled (default true)
298
299 Example:
300
301 .. literalinclude:: /../../tests/properties/fixtures/least-load002.yaml
302 :language: yaml
303 """
304 least = XML.SubElement(
305 xml_parent,
306 "org.bstick12.jenkinsci.plugins.leastload." "LeastLoadDisabledProperty",
307 )
308 mapping = [("disabled", "leastLoadDisabled", True)]
309 helpers.convert_mapping_to_xml(least, data, mapping, fail_required=True)
310
311
312 def throttle(registry, xml_parent, data):
313 """yaml: throttle
314 Throttles the number of builds for this job.
315
316 Requires the Jenkins :jenkins-plugins:`Throttle Concurrent Builds Plugin
317 <throttle-concurrents>`.
318
319 :arg str option: throttle `project` (throttle the project alone)
320 or `category` (throttle the project as part of one or more categories)
321 :arg int max-per-node: max concurrent builds per node (default 0)
322 :arg int max-total: max concurrent builds (default 0)
323 :arg bool enabled: whether throttling is enabled (default true)
324 :arg list categories: multiproject throttle categories
325 :arg bool matrix-builds: throttle matrix master builds (default true)
326 :arg bool matrix-configs: throttle matrix config builds (default false)
327 :arg str parameters-limit: prevent jobs with matching parameters from
328 running concurrently (default false)
329 :arg list parameters-check-list: Comma-separated list of parameters
330 to use when comparing jobs (optional)
331
332 Example:
333
334 .. literalinclude:: /../../tests/properties/fixtures/throttle001.yaml
335 :language: yaml
336 """
337 throttle = XML.SubElement(
338 xml_parent, "hudson.plugins.throttleconcurrents." "ThrottleJobProperty"
339 )
340 mapping = [
341 ("max-per-node", "maxConcurrentPerNode", "0"),
342 ("max-total", "maxConcurrentTotal", "0"),
343 ("enabled", "throttleEnabled", True),
344 ]
345 helpers.convert_mapping_to_xml(throttle, data, mapping, fail_required=True)
346 cat = data.get("categories", [])
347 if cat:
348 cn = XML.SubElement(throttle, "categories")
349 for c in cat:
350 XML.SubElement(cn, "string").text = str(c)
351
352 options_list = ("category", "project")
353 option = data.get("option")
354 if option not in options_list:
355 raise InvalidAttributeError("option", option, options_list)
356 mapping = [
357 ("", "throttleOption", option),
358 ("", "configVersion", "1"),
359 ("parameters-limit", "limitOneJobWithMatchingParams", False),
360 ]
361 helpers.convert_mapping_to_xml(throttle, data, mapping, fail_required=True)
362
363 matrixopt = XML.SubElement(throttle, "matrixOptions")
364 mapping = [
365 ("matrix-builds", "throttleMatrixBuilds", True),
366 ("matrix-configs", "throttleMatrixConfigurations", False),
367 ]
368 helpers.convert_mapping_to_xml(matrixopt, data, mapping, fail_required=True)
369
370 params_to_use = data.get("parameters-check-list", [])
371 XML.SubElement(throttle, "paramsToUseForLimit").text = ",".join(params_to_use)
372
373
374 def branch_api(registry, xml_parent, data):
375 """yaml: branch-api
376 Enforces a minimum time between builds based on the desired maximum rate.
377
378 Requires the Jenkins :jenkins-plugins:`Branch API Plugin <branch-api>`.
379
380 :arg int number-of-builds: The maximum number of builds allowed within
381 the specified time period. (default 1)
382 :arg str time-period: The time period within which the maximum number
383 of builds will be enforced. (default 'hour')
384
385 :valid values: **second** **minute** **hour**, **day**, **week**, **month**, **year**
386 :arg bool skip-rate-limit: Permit user triggered builds to
387 skip the rate limit (default false)
388
389 Minimal Example:
390
391 .. literalinclude::
392 /../../tests/properties/fixtures/branch-api-minimal.yaml
393 :language: yaml
394
395 Full example:
396
397 .. literalinclude::
398 /../../tests/properties/fixtures/branch-api-full.yaml
399 :language: yaml
400 """
401 branch = XML.SubElement(
402 xml_parent, "jenkins.branch." "RateLimitBranchProperty_-JobPropertyImpl"
403 )
404 branch.set("plugin", "branch-api")
405
406 valid_time_periods = ["second", "minute", "hour", "day", "week", "month", "year"]
407
408 mapping = [
409 ("time-period", "durationName", "hour", valid_time_periods),
410 ("number-of-builds", "count", 1),
411 ("skip-rate-limit", "userBoost", False),
412 ]
413 helpers.convert_mapping_to_xml(branch, data, mapping, fail_required=True)
414
415
416 def sidebar(registry, xml_parent, data):
417 """yaml: sidebar
418 Allows you to add links in the sidebar.
419 Requires the Jenkins :jenkins-plugins:`Sidebar-Link Plugin <sidebar-link>`.
420
421 :arg str url: url to link to (optional)
422 :arg str text: text for the link (optional)
423 :arg str icon: path to icon (optional)
424
425 Example:
426
427 .. literalinclude:: /../../tests/properties/fixtures/sidebar02.yaml
428 :language: yaml
429 """
430 sidebar = xml_parent.find("hudson.plugins.sidebar__link.ProjectLinks")
431 if sidebar is None:
432 sidebar = XML.SubElement(
433 xml_parent, "hudson.plugins.sidebar__link.ProjectLinks"
434 )
435 links = XML.SubElement(sidebar, "links")
436 else:
437 links = sidebar.find("links")
438 action = XML.SubElement(links, "hudson.plugins.sidebar__link.LinkAction")
439 mapping = [("url", "url", ""), ("text", "text", ""), ("icon", "icon", "")]
440 helpers.convert_mapping_to_xml(action, data, mapping, fail_required=True)
441
442
443 def inject(registry, xml_parent, data):
444 """yaml: inject
445 Allows you to inject environment variables into the build.
446
447 Requires the Jenkins :jenkins-plugins:`EnvInject Plugin <envinject>`.
448
449 :arg str properties-file: file to read with properties (optional)
450 :arg str properties-content: key=value properties (optional)
451 :arg str script-file: file with script to run (optional)
452 :arg str script-content: script to run (optional)
453 :arg str groovy-content: groovy script to run (optional)
454 :arg bool groovy-sandbox: run groovy script in sandbox (default false)
455 :arg bool load-from-master: load files from master (default false)
456 :arg bool enabled: injection enabled (default true)
457 :arg bool keep-system-variables: keep system variables (default true)
458 :arg bool keep-build-variables: keep build variable (default true)
459 :arg bool override-build-parameters: override build parameters
460 (default false)
461
462 Example:
463
464 .. literalinclude:: /../../tests/properties/fixtures/inject001.yaml
465 :language: yaml
466
467 """
468 inject = XML.SubElement(xml_parent, "EnvInjectJobProperty")
469 info = XML.SubElement(inject, "info")
470
471 mapping = [
472 ("properties-file", "propertiesFilePath", None),
473 ("properties-content", "propertiesContent", None),
474 ("script-file", "scriptFilePath", None),
475 ("script-content", "scriptContent", None),
476 ("load-from-master", "loadFilesFromMaster", False),
477 ]
478 helpers.convert_mapping_to_xml(info, data, mapping, fail_required=False)
479
480 # determine version of plugin
481 plugin_ver = registry.get_plugin_version("Groovy")
482
483 if plugin_ver >= "2.0.0":
484 secure_groovy_script = XML.SubElement(info, "secureGroovyScript")
485 mapping = [
486 ("groovy-content", "script", None),
487 ("groovy-sandbox", "sandbox", False),
488 ]
489 helpers.convert_mapping_to_xml(
490 secure_groovy_script, data, mapping, fail_required=False
491 )
492 else:
493 mapping = [("groovy-content", "groovyScriptContent", None)]
494 helpers.convert_mapping_to_xml(info, data, mapping, fail_required=False)
495
496 mapping = [
497 ("enabled", "on", True),
498 ("keep-system-variables", "keepJenkinsSystemVariables", True),
499 ("keep-build-variables", "keepBuildVariables", True),
500 ("override-build-parameters", "overrideBuildParameters", False),
501 ]
502 helpers.convert_mapping_to_xml(inject, data, mapping, fail_required=True)
503
504
505 def authenticated_build(registry, xml_parent, data):
506 """yaml: authenticated-build
507 Specifies an authorization matrix where only authenticated users
508 may trigger a build.
509
510 .. deprecated:: 0.1.0. Please use :ref:`authorization <authorization>`.
511
512 Example:
513
514 .. literalinclude::
515 /../../tests/properties/fixtures/authenticated_build.yaml
516 :language: yaml
517
518 """
519 # TODO: generalize this
520 security = XML.SubElement(
521 xml_parent, "hudson.security." "AuthorizationMatrixProperty"
522 )
523 XML.SubElement(
524 security, "permission"
525 ).text = "hudson.model.Item.Build:authenticated"
526
527
528 def authorization(registry, xml_parent, data, job_data):
529 """yaml: authorization
530 Specifies an authorization matrix
531 In 3.0 version of plugin was added support for explicitly assigning permissions
532 to groups or users with a given name to prevent confusion when names match either.
533
534 .. _authorization:
535
536 For *matrix-auth >= 3.0*
537 :arg list <inheritance-strategy>: `<inheritance-strategy>` the name of inheritance strategy
538
539 :<inheritance-strategy> values:
540 * **parent**
541 * **global**
542 * **none**
543
544 :arg list prefix:<name>:
545 * `prefix`
546 * **GROUP**
547 * **USER**
548 * `<name>` is the name of the group or user, containing
549
550 For *matrix-auth < 3.0*
551
552 :arg list <name>: `<name>` is the name of the group or user, containing
553
554
555 the list of rights to grant.
556
557 :<name> rights:
558 * **credentials-create**
559 * **credentials-delete**
560 * **credentials-manage-domains**
561 * **credentials-update**
562 * **credentials-view**
563 * **job-build**
564 * **job-cancel**
565 * **job-configure**
566 * **job-delete**
567 * **job-discover**
568 * **job-extended-read**
569 * **job-move**
570 * **job-read**
571 * **job-status**
572 * **job-workspace**
573 * **ownership-jobs**
574 * **run-delete**
575 * **run-replay**
576 * **run-update**
577 * **scm-tag**
578
579 Example:
580
581 .. literalinclude:: /../../tests/properties/fixtures/authorization01.yaml
582 :language: yaml
583 """
584
585 is_a_folder = job_data.get("project-type") in ("folder", "multibranch")
586
587 credentials = "com.cloudbees.plugins.credentials.CredentialsProvider."
588 ownership = "com.synopsys.arc.jenkins.plugins.ownership.OwnershipPlugin."
589
590 mapping = {
591 "credentials-create": "".join((credentials, "Create")),
592 "credentials-delete": "".join((credentials, "Delete")),
593 "credentials-manage-domains": "".join((credentials, "ManageDomains")),
594 "credentials-update": "".join((credentials, "Update")),
595 "credentials-view": "".join((credentials, "View")),
596 "job-build": "hudson.model.Item.Build",
597 "job-cancel": "hudson.model.Item.Cancel",
598 "job-configure": "hudson.model.Item.Configure",
599 "job-delete": "hudson.model.Item.Delete",
600 "job-discover": "hudson.model.Item.Discover",
601 "job-extended-read": "hudson.model.Item.ExtendedRead",
602 "job-move": "hudson.model.Item.Move",
603 "job-read": "hudson.model.Item.Read",
604 "job-status": "hudson.model.Item.ViewStatus",
605 "job-workspace": "hudson.model.Item.Workspace",
606 "ownership-jobs": "".join((ownership, "Jobs")),
607 "run-delete": "hudson.model.Run.Delete",
608 "run-replay": "hudson.model.Run.Replay",
609 "run-update": "hudson.model.Run.Update",
610 "scm-tag": "hudson.scm.SCM.Tag",
611 }
612
613 if data:
614 if is_a_folder:
615 element_name = "com.cloudbees.hudson.plugins.folder.properties.AuthorizationMatrixProperty"
616 else:
617 element_name = "hudson.security.AuthorizationMatrixProperty"
618 matrix = XML.SubElement(xml_parent, element_name)
619
620 inheritance_strategy = (
621 "org.jenkinsci.plugins.matrixauth.inheritance.InheritParentStrategy"
622 )
623 if data.get("inheritance-strategy") == "global":
624 inheritance_strategy = (
625 "org.jenkinsci.plugins.matrixauth.inheritance.InheritGlobalStrategy"
626 )
627 elif data.get("inheritance-strategy") == "none":
628 inheritance_strategy = (
629 "org.jenkinsci.plugins.matrixauth.inheritance.NonInheritingStrategy"
630 )
631 XML.SubElement(
632 matrix,
633 "inheritanceStrategy",
634 {"class": inheritance_strategy},
635 )
636
637 for (username, perms) in data.items():
638 if username != "inheritance-strategy":
639 for perm in perms:
640 pe = XML.SubElement(matrix, "permission")
641 try:
642 if username.upper().startswith(
643 "GROUP:"
644 ) or username.upper().startswith("USER:"):
645 pe.text = "{0}:{1}:{2}".format(
646 username.split(":")[0].upper(),
647 mapping[perm],
648 username.split(":")[1],
649 )
650 else:
651 pe.text = "{0}:{1}".format(mapping[perm], username)
652 except KeyError:
653 raise InvalidAttributeError(username, perm, mapping.keys())
654
655
656 def priority_sorter(registry, xml_parent, data):
657 """yaml: priority-sorter
658 Allows simple ordering of builds, using a configurable job priority.
659
660 Requires the Jenkins :jenkins-plugins:`Priority Sorter Plugin
661 <PrioritySorter>`.
662
663 :arg int priority: Priority of the job. Higher value means higher
664 priority, with 3 as the default priority. (required)
665
666 Example:
667
668 .. literalinclude::
669 /../../tests/properties/fixtures/priority_sorter002.yaml
670 :language: yaml
671 """
672 plugin_ver = registry.get_plugin_version("PrioritySorter")
673
674 if plugin_ver >= "3.0":
675 priority_sorter_tag = XML.SubElement(
676 xml_parent,
677 "jenkins.advancedqueue.jobinclusion." "strategy.JobInclusionJobProperty",
678 )
679
680 mapping = [("use", "useJobGroup", True), ("priority", "jobGroupName", None)]
681 elif plugin_ver >= "2.0":
682 priority_sorter_tag = XML.SubElement(
683 xml_parent, "jenkins.advancedqueue.priority." "strategy.PriorityJobProperty"
684 )
685
686 mapping = [("use", "useJobPriority", True), ("priority", "priority", None)]
687 else:
688 priority_sorter_tag = XML.SubElement(
689 xml_parent, "hudson.queueSorter." "PrioritySorterJobProperty"
690 )
691
692 mapping = [("priority", "priority", None)]
693
694 helpers.convert_mapping_to_xml(
695 priority_sorter_tag, data, mapping, fail_required=True
696 )
697
698
699 def build_blocker(registry, xml_parent, data):
700 """yaml: build-blocker
701 This plugin keeps the actual job in the queue
702 if at least one name of currently running jobs
703 is matching with one of the given regular expressions.
704
705 Requires the Jenkins :jenkins-plugins:`Build Blocker Plugin
706 <build-blocker-plugin>`.
707
708 :arg bool use-build-blocker: Enable or disable build blocker (default true)
709 :arg list blocking-jobs: One regular expression per line to select
710 blocking jobs by their names (required)
711 :arg str block-level: block build globally ('GLOBAL') or per node ('NODE')
712 (default 'GLOBAL')
713 :arg str queue-scanning: scan build queue for all builds ('ALL') or only
714 buildable builds ('BUILDABLE') (default 'DISABLED')
715
716 Example:
717
718 Minimal Example:
719
720 .. literalinclude::
721 /../../tests/properties/fixtures/build-blocker-minimal.yaml
722 :language: yaml
723
724 Full Example:
725
726 .. literalinclude::
727 /../../tests/properties/fixtures/build-blocker-full.yaml
728 :language: yaml
729 """
730 blocker = XML.SubElement(
731 xml_parent, "hudson.plugins." "buildblocker.BuildBlockerProperty"
732 )
733 if data is None or "blocking-jobs" not in data:
734 raise JenkinsJobsException("blocking-jobs field is missing")
735 elif data.get("blocking-jobs", None) is None:
736 raise JenkinsJobsException("blocking-jobs list must not be empty")
737
738 jobs = ""
739 for setting, value in data.items():
740 if setting == "blocking-jobs":
741 jobs = "\n".join(value)
742 block_level_types = ["GLOBAL", "NODE"]
743 queue_scan_types = ["DISABLED", "ALL", "BUILDABLE"]
744 mapping = [
745 ("use-build-blocker", "useBuildBlocker", True),
746 ("", "blockingJobs", jobs),
747 ("block-level", "blockLevel", "GLOBAL", block_level_types),
748 ("queue-scanning", "scanQueueFor", "DISABLED", queue_scan_types),
749 ]
750 helpers.convert_mapping_to_xml(blocker, data, mapping, fail_required=True)
751
752
753 def copyartifact(registry, xml_parent, data):
754 """yaml: copyartifact
755 Specify a list of projects that have access to copy the artifacts of
756 this project.
757
758 Requires the Jenkins :jenkins-plugins:`Copy Artifact plugin
759 <copyartifact>`.
760
761 :arg str projects: comma separated list of projects that can copy
762 artifacts of this project. Wild card character '*' is available.
763
764 Example:
765
766 .. literalinclude::
767 /../../tests/properties/fixtures/copyartifact.yaml
768 :language: yaml
769
770 """
771 copyartifact = XML.SubElement(
772 xml_parent,
773 "hudson.plugins." "copyartifact." "CopyArtifactPermissionProperty",
774 plugin="copyartifact",
775 )
776 if not data or not data.get("projects", None):
777 raise JenkinsJobsException("projects string must exist and " "not be empty")
778 projectlist = XML.SubElement(copyartifact, "projectNameList")
779 for project in str(data.get("projects")).split(","):
780 XML.SubElement(projectlist, "string").text = project
781
782
783 def batch_tasks(registry, xml_parent, data):
784 """yaml: batch-tasks
785 Batch tasks can be tasks for events like releases, integration, archiving,
786 etc. In this way, anyone in the project team can execute them in a way that
787 leaves a record.
788
789 A batch task consists of a shell script and a name. When you execute
790 a build, the shell script gets run on the workspace, just like a build.
791 Batch tasks and builds "lock" the workspace, so when one of those
792 activities is in progress, all the others will block in the queue.
793
794 Requires the Jenkins :jenkins-plugins:`Batch Task Plugin <batch-task>`.
795
796 :arg list batch-tasks: Batch tasks.
797
798 :Tasks:
799 * **name** (`str`) Task name.
800 * **script** (`str`) Task script.
801
802 Example:
803
804 .. literalinclude:: /../../tests/properties/fixtures/batch-task.yaml
805 :language: yaml
806
807 """
808 pdef = XML.SubElement(xml_parent, "hudson.plugins.batch__task.BatchTaskProperty")
809 tasks = XML.SubElement(pdef, "tasks")
810 for task in data:
811 batch_task = XML.SubElement(tasks, "hudson.plugins.batch__task.BatchTask")
812 mapping = [("name", "name", None), ("script", "script", None)]
813 helpers.convert_mapping_to_xml(batch_task, task, mapping, fail_required=True)
814
815
816 def heavy_job(registry, xml_parent, data):
817 """yaml: heavy-job
818 This plugin allows you to define "weight" on each job,
819 and making each job consume that many executors
820
821 Requires the Jenkins :jenkins-plugins:`Heavy Job Plugin <heavy-job>`.
822
823 :arg int weight: Specify the total number of executors
824 that this job should occupy (default 1)
825
826 Example:
827
828 .. literalinclude:: /../../tests/properties/fixtures/heavy-job.yaml
829 :language: yaml
830
831 """
832 heavyjob = XML.SubElement(
833 xml_parent, "hudson.plugins." "heavy__job.HeavyJobProperty"
834 )
835 mapping = [("weight", "weight", 1)]
836 helpers.convert_mapping_to_xml(heavyjob, data, mapping, fail_required=True)
837
838
839 def slave_utilization(registry, xml_parent, data):
840 """yaml: slave-utilization
841 This plugin allows you to specify the percentage of a slave's capacity a
842 job wants to use.
843
844 Requires the Jenkins :jenkins-plugins:`Slave Utilization Plugin
845 <slave-utilization-plugin>`.
846
847 :arg int slave-percentage: Specify the percentage of a slave's execution
848 slots that this job should occupy (default 0)
849 :arg bool single-instance-per-slave: Control whether concurrent instances
850 of this job will be permitted to run in parallel on a single slave
851 (default false)
852
853 Example:
854
855 .. literalinclude::
856 /../../tests/properties/fixtures/slave-utilization1.yaml
857 :language: yaml
858 """
859 utilization = XML.SubElement(
860 xml_parent, "com.suryagaddipati.jenkins.SlaveUtilizationProperty"
861 )
862
863 percent = int(data.get("slave-percentage", 0))
864 exclusive_node_access = True if percent else False
865
866 mapping = [
867 ("", "needsExclusiveAccessToNode", exclusive_node_access),
868 ("", "slaveUtilizationPercentage", percent),
869 ("single-instance-per-slave", "singleInstancePerSlave", False),
870 ]
871 helpers.convert_mapping_to_xml(utilization, data, mapping, fail_required=True)
872
873
874 def delivery_pipeline(registry, xml_parent, data):
875 """yaml: delivery-pipeline
876 Requires the Jenkins :jenkins-plugins:`Delivery Pipeline Plugin
877 <delivery-pipeline-plugin>`.
878
879 :arg str stage: Name of the stage for this job (default '')
880 :arg str task: Name of the task for this job (default '')
881 :arg str description: task description template for this job
882 (default '')
883
884 Minimal Example:
885
886 .. literalinclude::
887 /../../tests/properties/fixtures/delivery-pipeline-minimal.yaml
888 :language: yaml
889
890 Full Example:
891
892 .. literalinclude::
893 /../../tests/properties/fixtures/delivery-pipeline-full.yaml
894 :language: yaml
895 """
896 pipeline = XML.SubElement(xml_parent, "se.diabol.jenkins.pipeline.PipelineProperty")
897 pipeline.set("plugin", "delivery-pipeline-plugin")
898
899 mapping = [
900 ("stage", "stageName", ""),
901 ("task", "taskName", ""),
902 ("description", "descriptionTemplate", ""),
903 ]
904 helpers.convert_mapping_to_xml(pipeline, data, mapping, fail_required=True)
905
906
907 def zeromq_event(registry, xml_parent, data):
908 """yaml: zeromq-event
909 This is a Jenkins plugin that will publish Jenkins Job run events
910 (start, complete, finish) to a ZMQ PUB socket.
911
912 Requires the Jenkins `ZMQ Event Publisher.
913 <https://opendev.org/x/zmq-event-publisher>`_
914
915 Example:
916
917 .. literalinclude::
918 /../../tests/properties/fixtures/zeromq-event.yaml
919 :language: yaml
920
921 """
922
923 zmq_event = XML.SubElement(
924 xml_parent,
925 "org.jenkinsci.plugins." "ZMQEventPublisher.HudsonNotificationProperty",
926 )
927 mapping = [("", "enabled", True)]
928 helpers.convert_mapping_to_xml(zmq_event, data, mapping, fail_required=True)
929
930
931 def slack(registry, xml_parent, data):
932 """yaml: slack
933 Requires the Jenkins :jenkins-plugins:`Slack Plugin <slack>`.
934
935 When using Slack Plugin version < 2.0, Slack Plugin itself requires a
936 publisher aswell as properties please note that you have to add the
937 publisher to your job configuration aswell. When using Slack Plugin
938 version >= 2.0, you should only configure the publisher.
939
940 :arg bool notify-start: Send notification when the job starts
941 (default false)
942 :arg bool notify-success: Send notification on success. (default false)
943 :arg bool notify-aborted: Send notification when job is aborted. (
944 default false)
945 :arg bool notify-not-built: Send notification when job set to NOT_BUILT
946 status. (default false)
947 :arg bool notify-unstable: Send notification when job becomes unstable.
948 (default false)
949 :arg bool notify-failure: Send notification when job fails.
950 (default false)
951 :arg bool notify-back-to-normal: Send notification when job is
952 succeeding again after being unstable or failed. (default false)
953 :arg bool 'notify-repeated-failure': Send notification when job is
954 still failing after last failure. (default false)
955 :arg bool include-test-summary: Include the test summary. (default
956 False)
957 :arg bool include-custom-message: Include a custom message into the
958 notification. (default false)
959 :arg str custom-message: Custom message to be included. (default '')
960 :arg str room: A comma separated list of rooms / channels to send
961 the notifications to. (default '')
962
963 Example:
964
965 .. literalinclude::
966 /../../tests/properties/fixtures/slack001.yaml
967 :language: yaml
968 """
969 logger = logging.getLogger(__name__)
970
971 plugin_ver = registry.get_plugin_version("Slack Notification Plugin")
972
973 if plugin_ver >= "2.0":
974 logger.warning("properties section is not used with plugin version >= 2.0")
975
976 mapping = (
977 ("notify-start", "startNotification", False),
978 ("notify-success", "notifySuccess", False),
979 ("notify-aborted", "notifyAborted", False),
980 ("notify-not-built", "notifyNotBuilt", False),
981 ("notify-unstable", "notifyUnstable", False),
982 ("notify-failure", "notifyFailure", False),
983 ("notify-back-to-normal", "notifyBackToNormal", False),
984 ("notify-repeated-failure", "notifyRepeatedFailure", False),
985 ("include-test-summary", "includeTestSummary", False),
986 ("include-custom-message", "includeCustomMessage", False),
987 ("custom-message", "customMessage", ""),
988 ("room", "room", ""),
989 )
990
991 slack = XML.SubElement(
992 xml_parent, "jenkins.plugins.slack.SlackNotifier_-SlackJobProperty"
993 )
994
995 # Ensure that custom-message is set when include-custom-message is set
996 # to true.
997 if data.get("include-custom-message", False):
998 if not data.get("custom-message", ""):
999 raise MissingAttributeError("custom-message")
1000
1001 helpers.convert_mapping_to_xml(slack, data, mapping, fail_required=True)
1002
1003
1004 def rebuild(registry, xml_parent, data):
1005 """yaml: rebuild
1006 This plug-in allows the user to rebuild a parameterized build without
1007 entering the parameters again.It will also allow the user to edit the
1008 parameters before rebuilding.
1009
1010 Requires the Jenkins :jenkins-plugins:`Rebuild Plugin <rebuild>`.
1011
1012 :arg bool auto-rebuild: Rebuild without asking for parameters
1013 (default false)
1014 :arg bool rebuild-disabled: Disable rebuilding for this job
1015 (default false)
1016
1017 Minimal Example:
1018
1019 .. literalinclude:: /../../tests/properties/fixtures/rebuild-minimal.yaml
1020 :language: yaml
1021
1022 Full Example:
1023
1024 .. literalinclude:: /../../tests/properties/fixtures/rebuild-full.yaml
1025 :language: yaml
1026 """
1027 sub_element = XML.SubElement(xml_parent, "com.sonyericsson.rebuild.RebuildSettings")
1028 sub_element.set("plugin", "rebuild")
1029
1030 mapping = [
1031 ("auto-rebuild", "autoRebuild", False),
1032 ("rebuild-disabled", "rebuildDisabled", False),
1033 ]
1034 helpers.convert_mapping_to_xml(sub_element, data, mapping, fail_required=True)
1035
1036
1037 def build_discarder(registry, xml_parent, data):
1038 """yaml: build-discarder
1039
1040 :arg int days-to-keep: Number of days to keep builds for (default -1)
1041 :arg int num-to-keep: Number of builds to keep (default -1)
1042 :arg int artifact-days-to-keep: Number of days to keep builds with
1043 artifacts (default -1)
1044 :arg int artifact-num-to-keep: Number of builds with artifacts to keep
1045 (default -1)
1046
1047 Example:
1048
1049 .. literalinclude::
1050 /../../tests/properties/fixtures/build-discarder-001.yaml
1051 :language: yaml
1052
1053 .. literalinclude::
1054 /../../tests/properties/fixtures/build-discarder-002.yaml
1055 :language: yaml
1056 """
1057 base_sub = XML.SubElement(xml_parent, "jenkins.model.BuildDiscarderProperty")
1058 strategy = XML.SubElement(base_sub, "strategy")
1059 strategy.set("class", "hudson.tasks.LogRotator")
1060
1061 mappings = [
1062 ("days-to-keep", "daysToKeep", -1),
1063 ("num-to-keep", "numToKeep", -1),
1064 ("artifact-days-to-keep", "artifactDaysToKeep", -1),
1065 ("artifact-num-to-keep", "artifactNumToKeep", -1),
1066 ]
1067 helpers.convert_mapping_to_xml(strategy, data, mappings, fail_required=True)
1068
1069
1070 def build_failure_analyzer(registry, xml_parent, data):
1071 """yaml: build-failure-analyzer
1072
1073 Controls failure cause analysis for builds.
1074 Requires the Jenkins :jenkins-plugins:`Build Failure Analyzer Plugin
1075 <build-failure-analyzer>`.
1076
1077 Example:
1078
1079 .. literalinclude::
1080 /../../tests/properties/fixtures/build-failure-analyzer-001.yaml
1081 :language: yaml
1082
1083 .. literalinclude::
1084 /../../tests/properties/fixtures/build-failure-analyzer-003.yaml
1085 :language: yaml
1086 """
1087 base_sub = XML.SubElement(
1088 xml_parent, "com.sonyericsson.jenkins.plugins.bfa.model.ScannerJobProperty"
1089 )
1090
1091 mappings = [
1092 ("disabled", "doNotScan", False),
1093 ]
1094 helpers.convert_mapping_to_xml(base_sub, data, mappings, fail_required=True)
1095
1096
1097 def slave_prerequisites(registry, xml_parent, data):
1098 """yaml: slave-prerequisites
1099 This plugin allows you to check prerequisites on slave before
1100 a job can run a build on it
1101
1102 Requires the Jenkins :jenkins-plugins:`Slave Prerequisites Plugin
1103 <slave-prerequisites>`.
1104
1105 :arg str script: A script to be executed on slave node.
1106 If returning non 0 status, the node will be vetoed from hosting
1107 the build. (required)
1108 :arg str interpreter: Command line interpreter to be used for executing
1109 the prerequisite script - either `shell` for Unix shell or `cmd` for
1110 Windows batch script. (default shell)
1111
1112 Example:
1113
1114 .. literalinclude::
1115 /../../tests/properties/fixtures/slave-prerequisites-minimal.yaml
1116 :language: yaml
1117
1118 .. literalinclude::
1119 /../../tests/properties/fixtures/slave-prerequisites-full.yaml
1120 :language: yaml
1121 """
1122 prereqs = XML.SubElement(xml_parent, "com.cloudbees.plugins.JobPrerequisites")
1123
1124 mappings = [
1125 ("script", "script", None),
1126 (
1127 "interpreter",
1128 "interpreter",
1129 "shell",
1130 {"cmd": "windows batch command", "shell": "shell script"},
1131 ),
1132 ]
1133 helpers.convert_mapping_to_xml(prereqs, data, mappings, fail_required=True)
1134
1135
1136 def groovy_label(registry, xml_parent, data):
1137 """yaml: groovy-label
1138 This plugin allows you to use Groovy script to restrict where this project
1139 can be run.
1140
1141 Requires the Jenkins :jenkins-plugins:`Groovy Label Assignment Plugin
1142 <groovy-label-assignment>`.
1143
1144 Return value from Groovy script is treated as Label Expression.
1145 It is treated as followings:
1146
1147 - A non-string value will be converted to a string using toString()
1148 - When null or blank string is returned, node restriction does not take
1149 effect (or is not overwritten).
1150 - When exception occurred or Label Expression is not parsed correctly,
1151 builds are canceled.
1152
1153 :arg str script: Groovy script (default '')
1154 :arg bool sandbox: Use Groovy Sandbox. (default false)
1155 If checked, run this Groovy script in a sandbox with limited abilities.
1156 If unchecked, and you are not a Jenkins administrator, you will need to
1157 wait for an administrator to approve the script
1158 :arg list classpath: Additional classpath entries accessible from
1159 the script, each of which should be an absolute local path or
1160 URL to a JAR file, according to "The file URI Scheme" (optional)
1161
1162 Minimal Example:
1163
1164 .. literalinclude::
1165 /../../tests/properties/fixtures/groovy-label-minimal.yaml
1166 :language: yaml
1167
1168 Full Example:
1169
1170 .. literalinclude::
1171 /../../tests/properties/fixtures/groovy-label-full.yaml
1172 :language: yaml
1173 """
1174 sub_element = XML.SubElement(
1175 xml_parent,
1176 "jp.ikedam.jenkins.plugins."
1177 "groovy__label__assignment."
1178 "GroovyLabelAssignmentProperty",
1179 )
1180 sub_element.set("plugin", "groovy-label-assignment")
1181 security = XML.SubElement(sub_element, "secureGroovyScript")
1182 security.set("plugin", "script-security")
1183 mapping = [("script", "script", ""), ("sandbox", "sandbox", False)]
1184
1185 helpers.convert_mapping_to_xml(security, data, mapping, fail_required=True)
1186 if data and "classpath" in data:
1187 classpath = XML.SubElement(security, "classpath")
1188 for value in data["classpath"]:
1189 entry = XML.SubElement(classpath, "entry")
1190 XML.SubElement(entry, "url").text = value
1191
1192
1193 def lockable_resources(registry, xml_parent, data):
1194 """yaml: lockable-resources
1195 Requires the Jenkins :jenkins-plugins:`Lockable Resources Plugin
1196 <lockable-resources>`.
1197
1198 :arg str resources: List of required resources, space separated.
1199 (required, mutual exclusive with label)
1200 :arg str label: If you have created a pool of resources, i.e. a label,
1201 you can take it into use here. The build will select the resource(s)
1202 from the pool that includes all resources sharing the given label.
1203 (required, mutual exclusive with resources)
1204 :arg str var-name: Name for the Jenkins variable to store the reserved
1205 resources in. Leave empty to disable. (default '')
1206 :arg int number: Number of resources to request, empty value or 0 means
1207 all. This is useful, if you have a pool of similar resources,
1208 from which you want one or more to be reserved. (default 0)
1209 :arg str match-script: Groovy script to reserve resource based on its
1210 properties. Leave empty to disable. (default None)
1211 :arg bool groovy-sandbox: Execute the provided match-script in Groovy
1212 sandbox. Leave empty to disable. (default False)
1213
1214 Example:
1215
1216 .. literalinclude::
1217 /../../tests/properties/fixtures/lockable_resources_minimal.yaml
1218 :language: yaml
1219
1220 .. literalinclude::
1221 /../../tests/properties/fixtures/lockable_resources_label.yaml
1222 :language: yaml
1223
1224 .. literalinclude::
1225 /../../tests/properties/fixtures/lockable_resources_full.yaml
1226 :language: yaml
1227
1228 .. literalinclude::
1229 /../../tests/properties/fixtures/lockable_resources_groovy.yaml
1230 :language: yaml
1231 """
1232 lockable_resources = XML.SubElement(
1233 xml_parent, "org.jenkins.plugins.lockableresources.RequiredResourcesProperty"
1234 )
1235 if data.get("resources") and data.get("label"):
1236 raise AttributeConflictError("resources", ("label",))
1237 mapping = [
1238 ("resources", "resourceNames", ""),
1239 ("var-name", "resourceNamesVar", ""),
1240 ("number", "resourceNumber", 0),
1241 ("label", "labelName", ""),
1242 ]
1243 helpers.convert_mapping_to_xml(
1244 lockable_resources, data, mapping, fail_required=True
1245 )
1246 secure_groovy_script = XML.SubElement(lockable_resources, "resourceMatchScript")
1247 mapping = [("match-script", "script", None), ("groovy-sandbox", "sandbox", False)]
1248 helpers.convert_mapping_to_xml(
1249 secure_groovy_script, data, mapping, fail_required=False
1250 )
1251
1252
1253 def docker_container(registry, xml_parent, data):
1254 """yaml: docker-container
1255 Requires the Jenkins: :jenkins-plugins:`Docker Plugin <docker-plugin>`.
1256
1257 :arg str docker-registry-url: URL of the Docker registry. (default '')
1258 :arg str credentials-id: Credentials Id for the Docker registey.
1259 (default '')
1260 :arg bool commit-on-success: When a job completes, the docker slave
1261 instance is committed with repository based on the job name and build
1262 number as tag. (default false)
1263 :arg str additional-tag: Additional tag to apply to the docker slave
1264 instance when committing it. (default '')
1265 :arg bool push-on-success: Also push the resulting image when committing
1266 the docker slave instance. (default false)
1267 :arg bool clean-local-images: Clean images from the local daemon after
1268 building. (default true)
1269
1270 Minimal Example:
1271
1272 .. literalinclude::
1273 /../../tests/properties/fixtures/docker-container-minimal.yaml
1274 :language: yaml
1275
1276 Full Example:
1277
1278 .. literalinclude::
1279 /../../tests/properties/fixtures/docker-container-full.yaml
1280 :language: yaml
1281 """
1282 xml_docker = XML.SubElement(
1283 xml_parent, "com.nirima.jenkins.plugins.docker.DockerJobProperty"
1284 )
1285
1286 registry = XML.SubElement(xml_docker, "registry")
1287 registry.set("plugin", "docker-commons")
1288 registry_mapping = [
1289 ("docker-registry-url", "url", ""),
1290 ("credentials-id", "credentialsId", ""),
1291 ]
1292 helpers.convert_mapping_to_xml(
1293 registry, data, registry_mapping, fail_required=False
1294 )
1295 mapping = [
1296 ("commit-on-success", "tagOnCompletion", False),
1297 ("additional-tag", "additionalTag", ""),
1298 ("push-on-success", "pushOnSuccess", False),
1299 ("clean-local-images", "cleanImages", True),
1300 ]
1301 helpers.convert_mapping_to_xml(xml_docker, data, mapping, fail_required=True)
1302
1303
1304 def disable_resume(registry, xml_parent, data):
1305 """yaml: disable-resume
1306 Do not allow the pipeline to resume if the master restarts
1307
1308 Requires the Jenkins :jenkins-plugins:`Pipeline Job Plugin
1309 <workflow-aggregator>`.
1310
1311 Example:
1312
1313 .. literalinclude::
1314 /../../tests/properties/fixtures/disable-resume.yaml
1315 :language: yaml
1316
1317 """
1318 XML.SubElement(
1319 xml_parent,
1320 "org.jenkinsci.plugins.workflow.job.properties." "DisableResumeJobProperty",
1321 )
1322
1323
1324 def resource_gating(registry, xml_parent, data):
1325 """yaml: resource-gating
1326 Jenkins Gating enables requiring external resources to be available before
1327 build starts.
1328
1329 Requires the Jenkins: :jenkins-plugins:`Jenkins Gating <gating-core>`.
1330
1331 :arg list resources: Resource identifiers to be up before building
1332
1333 Example:
1334
1335 .. literalinclude:: /../../tests/properties/fixtures/gating-core.yaml
1336 :language: yaml
1337 """
1338 if "resources" not in data.keys():
1339 raise MissingAttributeError("resources")
1340
1341 gating = XML.SubElement(
1342 xml_parent, "io.jenkins.plugins.gating.ResourceRequirementProperty"
1343 )
1344 gating.set("plugin", "gating-core")
1345
1346 resources = XML.SubElement(gating, "resources")
1347 resources.set("class", "java.util.Collections$UnmodifiableRandomAccessList")
1348 resources.set("resolves-to", "java.util.Collections$UnmodifiableList")
1349
1350 c = XML.SubElement(resources, "c")
1351 c.set("class", "list")
1352 for resource in data["resources"]:
1353 XML.SubElement(c, "string").text = str(resource)
1354
1355 lst = XML.SubElement(resources, "list")
1356 lst.set("reference", "../c")
1357
1358
1359 def cachet_gating(registry, xml_parent, data):
1360 """yaml: cachet-gating
1361 The Cachet Gating Plugin provides a gating mechanism
1362 based on the availability of resources.
1363
1364 Requires the Jenkins: :jenkins-plugins:`Cachet Gate Plugin
1365 <cachet-gating>`.
1366
1367 :arg bool required-resources: Confirm availability of listed
1368 resources before building. Requires the list of resources to
1369 also be defined. (default true)
1370 :arg list resources: which resources to gate
1371
1372 Example:
1373
1374 .. literalinclude:: /../../tests/properties/fixtures/cachet-gating.yaml
1375 :language: yaml
1376 """
1377 cachet = XML.SubElement(
1378 xml_parent, "com.redhat.jenkins.plugins.cachet.CachetJobProperty"
1379 )
1380 cachet.set("plugin", "cachet-gating")
1381
1382 mapping = [("required-resources", "requiredResources", True)]
1383 helpers.convert_mapping_to_xml(cachet, data, mapping, fail_required=True)
1384
1385 resources_data = data.get("resources", [])
1386 if resources_data:
1387 resources = XML.SubElement(cachet, "resources")
1388 for resource in resources_data:
1389 XML.SubElement(resources, "string").text = str(resource)
1390
1391
1392 def office_365_connector(registry, xml_parent, data):
1393 """yaml: office-365-connector
1394 Used to send actionable messages to MS Outlook or Teams
1395
1396 Requires the Jenkins: :jenkins-plugins:` Office-365-Connector Plugin
1397 <Office-365-Connector>`.
1398
1399 :arg list webhooks: List of webhooks (required)
1400
1401 * **url** (srt): URL generated in the Office 365 Connectors page (required)
1402 * **name** (str): Allows to provide name fo the connection. Name is not
1403 mandatory but helps managing when there are many connection
1404 assigned to the build (optional, default '')
1405 * **start-notification** (bool): If the notification should be sent on
1406 start of build (optional, default False)
1407 * **notify-success** (bool): If the notification should be sent on
1408 succeeded build (optional, default True)
1409 * **notify-aborted** (bool): If the notification should be sent on
1410 aborted build (optional, default False)
1411 * **notify-not-built** (bool): If the notification should be sent on
1412 not built build (optional, default False)
1413 * **notify-unstable** (bool): If the notification should be sent on
1414 unstable build (optional, default True)
1415 * **notify-failure** (bool): If the notification should be sent on
1416 failed build (optional, default True)
1417 * **notify-back-to-normal** (bool): If the notification should be sent on
1418 back to normal build (optional, default True)
1419 * **notify-repeated-failure** (bool): If the notification should be sent on
1420 repeated failures (optional, default False)
1421 * **timeout** (int): connection timeout (in milliseconds) for TCP and HTTP
1422 (optional, default 30000)
1423 * **macros** (list): List of macros
1424
1425 * **template** (str)
1426 **value** (str)
1427
1428 * **fact-definitions** (list): List of fact definitions
1429
1430 * **name** (str)
1431 **template** (str)
1432
1433 Example:
1434
1435 .. literalinclude:: /../../tests/properties/fixtures/office-365-connector-full.yaml
1436 :language: yaml
1437 """
1438
1439 office_365_connector = XML.SubElement(
1440 xml_parent, "jenkins.plugins.office365connector.WebhookJobProperty"
1441 )
1442 office_365_connector.set("plugin", "Office-365-Connector")
1443 webhooks = XML.SubElement(office_365_connector, "webhooks")
1444
1445 webhook_mapping = [
1446 ("url", "url", None),
1447 ("name", "name", ""),
1448 ("start-notification", "startNotification", False),
1449 ("notify-success", "notifySuccess", True),
1450 ("notify-aborted", "notifyAborted", False),
1451 ("notify-not-built", "notifyNotBuilt", False),
1452 ("notify-unstable", "notifyUnstable", True),
1453 ("notify-failure", "notifyFailure", True),
1454 ("notify-back-to-normal", "notifyBackToNormal", True),
1455 ("notify-repeated-failure", "notifyRepeatedFailure", False),
1456 ("timeout", "timeout", 30000),
1457 ]
1458 macro_mapping = [("template", "template", None), ("value", "value", None)]
1459 fact_definition_mapping = [("name", "name", None), ("template", "template", None)]
1460
1461 if "webhooks" not in data.keys():
1462 raise MissingAttributeError("webhooks")
1463
1464 for webhook_data in data["webhooks"]:
1465 webhook_element = XML.SubElement(
1466 webhooks, "jenkins.plugins.office365connector.Webhook"
1467 )
1468 helpers.convert_mapping_to_xml(
1469 webhook_element, webhook_data, webhook_mapping, fail_required=True
1470 )
1471 if "macros" in webhook_data.keys():
1472 macros = XML.SubElement(webhook_element, "macros")
1473 for macro_data in webhook_data["macros"]:
1474 macro_element = XML.SubElement(
1475 macros, "jenkins.plugins.office365connector.model.Macro"
1476 )
1477 helpers.convert_mapping_to_xml(
1478 macro_element, macro_data, macro_mapping, fail_required=True
1479 )
1480 if "fact-definitions" in webhook_data.keys():
1481 fact_definitions = XML.SubElement(webhook_element, "factDefinitions")
1482 for fact_definition_data in webhook_data["fact-definitions"]:
1483 fact_definition_element = XML.SubElement(
1484 fact_definitions,
1485 "jenkins.plugins.office365connector.model.FactDefinition",
1486 )
1487 helpers.convert_mapping_to_xml(
1488 fact_definition_element,
1489 fact_definition_data,
1490 fact_definition_mapping,
1491 fail_required=True,
1492 )
1493
1494
1495 def speed_durability(registry, xml_parent, data):
1496 """yaml: speed-durability
1497 This setting allows users to change the default durability mode
1498 for running Pipelines.
1499
1500 :arg str hint: speed durability hint to be used, can be performance-optimized,
1501 survivable-non-atomic, max-survivability
1502
1503 Example:
1504
1505 .. literalinclude::
1506 /../../tests/properties/fixtures/speed-durability.yaml
1507 :language: yaml
1508 """
1509 dhp = XML.SubElement(
1510 xml_parent,
1511 "org.jenkinsci.plugins.workflow.job.properties.DurabilityHintJobProperty",
1512 )
1513 choicedict = {
1514 "performance-optimized": "PERFORMANCE_OPTIMIZED",
1515 "survivable-non-atomic": "SURVIVABLE_NONATOMIC",
1516 "max-survivability": "MAX_SURVIVABILITY",
1517 }
1518 mapping = [("hint", "hint", None, choicedict)]
1519 helpers.convert_mapping_to_xml(dhp, data, mapping, fail_required=True)
1520
1521
1522 class Properties(jenkins_jobs.modules.base.Base):
1523 sequence = 20
1524
1525 component_type = "property"
1526 component_list_type = "properties"
1527
1528 def gen_xml(self, xml_parent, data):
1529 xml_properties = xml_parent.find("properties")
1530 if xml_properties is None:
1531 xml_properties = XML.SubElement(xml_parent, "properties")
1532
1533 self.dispatch_component_list(
1534 "property", data.get("properties", []), xml_properties, job_data=data
1535 )