Debian Codegraph @

jenkins_jobs/modules/wrappers.py

raw
1 # Copyright 2012 Hewlett-Packard Development Company, L.P.
2 #
3 # Licensed under the Apache License, Version 2.0 (the "License");
4 # you may not use this file except in compliance with the License.
5 # You may obtain a copy of the License at
6 #
7 # http://www.apache.org/licenses/LICENSE-2.0
8 #
9 # Unless required by applicable law or agreed to in writing, software
10 # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11 # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12 # License for the specific language governing permissions and limitations
13 # under the License.
14
15
16 """
17 Wrappers can alter the way the build is run as well as the build output.
18
19 **Component**: wrappers
20 :Macro: wrapper
21 :Entry Point: jenkins_jobs.wrappers
22
23 """
24
25 import logging
26 import xml.etree.ElementTree as XML
27
28 from jenkins_jobs.errors import InvalidAttributeError
29 from jenkins_jobs.errors import JenkinsJobsException
30 import jenkins_jobs.modules.base
31 from jenkins_jobs.modules.builders import create_builders
32 import jenkins_jobs.modules.helpers as helpers
33
34 logger = logging.getLogger(__name__)
35
36 MIN_TO_SEC = 60
37
38
39 def docker_custom_build_env(registry, xml_parent, data):
40 """yaml: docker-custom-build-env
41 Allows the definition of a build environment for a job using a Docker
42 container.
43
44 Requires the Jenkins :jenkins-plugins:`CloudBees Docker Custom Build
45 Environment Plugin<docker-custom-build-environment>`.
46
47 :arg str image-type: Docker image type. Valid values and their
48 additional attributes described in the image_types_ table
49 :arg str docker-tool: The name of the docker installation to use
50 (default 'Default')
51 :arg str host: URI to the docker host you are using
52 :arg str credentials-id: Argument to specify the ID of credentials to use
53 for docker host (optional)
54 :arg str registry-credentials-id: Argument to specify the ID of
55 credentials to use for docker registry (optional)
56 :arg list volumes: Volumes to bind mound from slave host into container
57
58 :volume: * **host-path** (`str`) Path on host
59 * **path** (`str`) Path inside container
60
61 :arg bool verbose: Log docker commands executed by plugin on build log
62 (default false)
63 :arg bool privileged: Run in privileged mode (default false)
64 :arg bool force-pull: Force pull (default false)
65 :arg str group: The user to run build has to be the same as the Jenkins
66 slave user so files created in workspace have adequate owner and
67 permission set
68 :arg str command: Container start command (default '/bin/cat')
69 :arg str net: Network bridge (default 'bridge')
70 :arg str memory-limit: Configure the limit memory
71 constraint (default '')
72 :arg str cpu-shares: Configure the CPU shares
73 constraint (default '')
74
75 .. _image_types:
76
77 ================== ====================================================
78 Image Type Description
79 ================== ====================================================
80 dockerfile Build docker image from a Dockerfile in project
81 workspace. With this option, project can define the
82 build environment as a Dockerfile stored in SCM with
83 project source code
84
85 :context-path: (str) Path to docker context
86 (default '.')
87 :dockerfile: (str) Use an alternate Dockerfile to
88 build the container hosting this build
89 (default 'Dockerfile')
90 pull Pull specified docker image from Docker repository
91
92 :image: (str) Image id/tag
93 ================== ====================================================
94
95 Example:
96
97 .. literalinclude::
98 /../../tests/wrappers/fixtures/docker-custom-build-env001.yaml
99 :language: yaml
100 """
101 core_prefix = "com.cloudbees.jenkins.plugins.okidocki."
102 entry_xml = XML.SubElement(xml_parent, core_prefix + "DockerBuildWrapper")
103 entry_xml.set("plugin", "docker-custom-build-environment")
104
105 selectorobj = XML.SubElement(entry_xml, "selector")
106 image_type = data["image-type"]
107 if image_type == "dockerfile":
108 selectorobj.set("class", core_prefix + "DockerfileImageSelector")
109 dockerfile_mapping = [
110 ("context-path", "contextPath", "."),
111 ("dockerfile", "dockerfile", "Dockerfile"),
112 ]
113 helpers.convert_mapping_to_xml(
114 selectorobj, data, dockerfile_mapping, fail_required=True
115 )
116
117 elif image_type == "pull":
118 selectorobj.set("class", core_prefix + "PullDockerImageSelector")
119 pull_mapping = [("image", "image", "")]
120 helpers.convert_mapping_to_xml(
121 selectorobj, data, pull_mapping, fail_required=True
122 )
123
124 XML.SubElement(entry_xml, "dockerInstallation").text = data.get(
125 "docker-tool", "Default"
126 )
127
128 host = XML.SubElement(entry_xml, "dockerHost")
129 host.set("plugin", "docker-commons")
130 mapping_optional = [
131 ("host", "uri", None),
132 ("credentials-id", "credentialsId", None),
133 ]
134 helpers.convert_mapping_to_xml(host, data, mapping_optional, fail_required=False)
135
136 XML.SubElement(entry_xml, "dockerRegistryCredentials").text = data.get(
137 "registry-credentials-id", ""
138 )
139 volumesobj = XML.SubElement(entry_xml, "volumes")
140 volumes = data.get("volumes", [])
141 if not volumes:
142 volumesobj.set("class", "empty-list")
143 else:
144 for volume in volumes:
145 volumeobj = XML.SubElement(
146 volumesobj, "com.cloudbees.jenkins.plugins.okidocki.Volume"
147 )
148 XML.SubElement(volumeobj, "hostPath").text = volume["volume"].get(
149 "host-path", ""
150 )
151 XML.SubElement(volumeobj, "path").text = volume["volume"].get("path", "")
152 mapping = [
153 ("force-pull", "forcePull", False),
154 ("privileged", "privileged", False),
155 ("verbose", "verbose", False),
156 ("group", "group", ""),
157 ("command", "command", "/bin/cat"),
158 ("net", "net", "bridge"),
159 ("memory-limit", "memory", ""),
160 ("cpu-shares", "cpu", ""),
161 ]
162 helpers.convert_mapping_to_xml(entry_xml, data, mapping, fail_required=True)
163
164
165 def ci_skip(registry, xml_parent, data):
166 """yaml: ci-skip
167 Skip making a build for certain push.
168 Just add [ci skip] into your commit's message to let Jenkins know,
169 that you do not want to perform build for the next push.
170
171 Requires the Jenkins :jenkins-plugins:`Ci Skip Plugin <ci-skip>`.
172
173 Example:
174
175 .. literalinclude:: /../../tests/wrappers/fixtures/ci-skip001.yaml
176 """
177 rpobj = XML.SubElement(xml_parent, "ruby-proxy-object")
178 robj = XML.SubElement(
179 rpobj,
180 "ruby-object",
181 {"pluginid": "ci-skip", "ruby-class": "Jenkins::Tasks::BuildWrapperProxy"},
182 )
183 pluginid = XML.SubElement(
184 robj, "pluginid", {"pluginid": "ci-skip", "ruby-class": "String"}
185 )
186 pluginid.text = "ci-skip"
187 obj = XML.SubElement(
188 robj, "object", {"pluginid": "ci-skip", "ruby-class": "CiSkipWrapper"}
189 )
190 XML.SubElement(obj, "ci__skip", {"pluginid": "ci-skip", "ruby-class": "NilClass"})
191
192
193 def config_file_provider(registry, xml_parent, data):
194 """yaml: config-file-provider
195 Provide configuration files (i.e., settings.xml for maven etc.)
196 which will be copied to the job's workspace.
197
198 Requires the Jenkins :jenkins-plugins:`Config File Provider Plugin
199 <config-file-provider>`.
200
201 :arg list files: List of managed config files made up of three
202 parameters
203
204 :files: * **file-id** (`str`) -- The identifier for the managed config
205 file
206 * **target** (`str`) -- Define where the file should be created
207 (default '')
208 * **variable** (`str`) -- Define an environment variable to be
209 used (default '')
210 * **replace-tokens** (`bool`) -- Replace tokens in config file.
211 For example "password: ${PYPI_JENKINS_PASS}" will be replaced
212 with the global variable configured in Jenkins.
213
214 Full Example:
215
216 .. literalinclude::
217 /../../tests/wrappers/fixtures/config-file-provider-full.yaml
218
219 Minimal Example:
220
221 .. literalinclude::
222 /../../tests/wrappers/fixtures/config-file-provider-minimal.yaml
223 """
224 cfp = XML.SubElement(
225 xml_parent,
226 "org.jenkinsci.plugins.configfiles." "buildwrapper.ConfigFileBuildWrapper",
227 )
228 cfp.set("plugin", "config-file-provider")
229 helpers.config_file_provider_builder(cfp, data)
230
231
232 def logfilesize(registry, xml_parent, data):
233 """yaml: logfilesize
234 Abort the build if its logfile becomes too big.
235
236 Requires the Jenkins :jenkins-plugins:`Logfilesizechecker Plugin
237 <logfilesizechecker>`.
238
239 :arg bool set-own: Use job specific maximum log size instead of global
240 config value (default false).
241 :arg bool fail: Make builds aborted by this wrapper be marked as "failed"
242 (default false).
243 :arg int size: Abort the build if logfile size is bigger than this
244 value (in MiB, default 128). Only applies if set-own is true.
245
246 Full Example:
247
248 .. literalinclude:: /../../tests/wrappers/fixtures/logfilesize-full.yaml
249
250 Minimal Example:
251
252 .. literalinclude:: /../../tests/wrappers/fixtures/logfilesize-minimal.yaml
253 """
254 lfswrapper = XML.SubElement(
255 xml_parent, "hudson.plugins.logfilesizechecker." "LogfilesizecheckerWrapper"
256 )
257 lfswrapper.set("plugin", "logfilesizechecker")
258
259 mapping = [
260 ("set-own", "setOwn", False),
261 ("size", "maxLogSize", 128),
262 ("fail", "failBuild", False),
263 ]
264 helpers.convert_mapping_to_xml(lfswrapper, data, mapping, fail_required=True)
265
266
267 def timeout(registry, xml_parent, data):
268 """yaml: timeout
269 Abort the build if it runs too long.
270
271 Requires the Jenkins :jenkins-plugins:`Build Timeout Plugin
272 <build-timeout>`.
273
274 :arg bool fail: Mark the build as failed (default false)
275 :arg bool abort: Mark the build as aborted (default false)
276 :arg bool abort-and-restart: Mark the build as aborted, then restart.
277 Count of restarts can be set via `max-restarts`
278 (default false) (Version >= 1.17).
279 :arg bool write-description: Write a message in the description
280 (default false)
281 :arg int max-restarts: Count of maximum restarts.
282 0 means without a limit (default 0) (Version >= 1.17).
283 :arg int timeout: Abort the build after this number of minutes (default 3)
284 :arg str timeout-var: Export an environment variable to reference the
285 timeout value (optional)
286 :arg str type: Timeout type to use (default absolute)
287 :type values:
288 * **likely-stuck**
289 * **no-activity**
290 * **elastic**
291 * **absolute**
292 * **deadline**
293
294 :arg int elastic-percentage: Percentage of the three most recent builds
295 where to declare a timeout, only applies to **elastic** type.
296 (default 0)
297 :arg int elastic-number-builds: Number of builds to consider computing
298 average duration, only applies to **elastic** type. (default 3)
299 :arg int elastic-default-timeout: Timeout to use if there were no previous
300 builds, only applies to **elastic** type. (default 3)
301
302 :arg str deadline-time: Build terminate automatically at next deadline time
303 (HH:MM:SS), only applies to **deadline** type. (default 0:00:00)
304 :arg int deadline-tolerance: Period in minutes after deadline when a job
305 should be immediately aborted, only applies to **deadline** type.
306 (default 1)
307
308 Example (Version < 1.14):
309
310 .. literalinclude:: /../../tests/wrappers/fixtures/timeout/timeout001.yaml
311
312 .. literalinclude:: /../../tests/wrappers/fixtures/timeout/timeout002.yaml
313
314 .. literalinclude:: /../../tests/wrappers/fixtures/timeout/timeout003.yaml
315
316 Example (Version >= 1.14):
317
318 .. literalinclude::
319 /../../tests/wrappers/fixtures/timeout/version-1.14/absolute001.yaml
320
321 .. literalinclude::
322 /../../tests/wrappers/fixtures/timeout/version-1.14/no-activity001.yaml
323
324 .. literalinclude::
325 /../../tests/wrappers/fixtures/timeout/version-1.14/likely-stuck001.yaml
326
327 .. literalinclude::
328 /../../tests/wrappers/fixtures/timeout/version-1.14/elastic001.yaml
329
330 .. literalinclude::
331 /../../tests/wrappers/fixtures/timeout/version-1.15/deadline001.yaml
332
333 """
334 prefix = "hudson.plugins.build__timeout."
335 twrapper = XML.SubElement(xml_parent, prefix + "BuildTimeoutWrapper")
336
337 plugin_ver = registry.get_plugin_version(
338 "Build Timeout", "Jenkins build timeout plugin"
339 )
340
341 valid_strategies = [
342 "absolute",
343 "no-activity",
344 "likely-stuck",
345 "elastic",
346 "deadline",
347 ]
348
349 # NOTE(toabctl): if we don't know the version assume that we
350 # use a newer version of the plugin
351 if plugin_ver >= "1.14":
352 strategy = data.get("type", "absolute")
353 if strategy not in valid_strategies:
354 InvalidAttributeError("type", strategy, valid_strategies)
355
356 if strategy == "absolute":
357 strategy_element = XML.SubElement(
358 twrapper,
359 "strategy",
360 {
361 "class": "hudson.plugins.build_timeout."
362 "impl.AbsoluteTimeOutStrategy"
363 },
364 )
365 mapping = [("timeout", "timeoutMinutes", 3)]
366 helpers.convert_mapping_to_xml(
367 strategy_element, data, mapping, fail_required=True
368 )
369 elif strategy == "no-activity":
370 strategy_element = XML.SubElement(
371 twrapper,
372 "strategy",
373 {
374 "class": "hudson.plugins.build_timeout."
375 "impl.NoActivityTimeOutStrategy"
376 },
377 )
378 timeout_sec = int(data.get("timeout", 3)) * MIN_TO_SEC
379 mapping = [("", "timeoutSecondsString", timeout_sec)]
380 helpers.convert_mapping_to_xml(
381 strategy_element, data, mapping, fail_required=True
382 )
383 elif strategy == "likely-stuck":
384 strategy_element = XML.SubElement(
385 twrapper,
386 "strategy",
387 {
388 "class": "hudson.plugins.build_timeout."
389 "impl.LikelyStuckTimeOutStrategy"
390 },
391 )
392 mapping = [("timeout", "timeoutMinutes", 3)]
393 helpers.convert_mapping_to_xml(
394 strategy_element, data, mapping, fail_required=True
395 )
396 elif strategy == "elastic":
397 strategy_element = XML.SubElement(
398 twrapper,
399 "strategy",
400 {
401 "class": "hudson.plugins.build_timeout."
402 "impl.ElasticTimeOutStrategy"
403 },
404 )
405 mapping = [
406 ("elastic-percentage", "timeoutPercentage", 0),
407 ("elastic-number-builds", "numberOfBuilds", 0),
408 ("elastic-default-timeout", "timeoutMinutesElasticDefault", 3),
409 ]
410 helpers.convert_mapping_to_xml(
411 strategy_element, data, mapping, fail_required=True
412 )
413
414 elif strategy == "deadline":
415 strategy_element = XML.SubElement(
416 twrapper,
417 "strategy",
418 {
419 "class": "hudson.plugins.build_timeout."
420 "impl.DeadlineTimeOutStrategy"
421 },
422 )
423 deadline_time = str(data.get("deadline-time", "0:00:00"))
424 deadline_tolerance = int(data.get("deadline-tolerance", 1))
425 mapping = [
426 ("", "deadlineTime", deadline_time),
427 ("", "deadlineToleranceInMinutes", deadline_tolerance),
428 ]
429 helpers.convert_mapping_to_xml(
430 strategy_element, data, mapping, fail_required=True
431 )
432
433 all_actions = ["fail", "abort"]
434 actions = []
435
436 if plugin_ver >= "1.17":
437 all_actions.append("abort-and-restart")
438
439 for action in all_actions:
440 if str(data.get(action, "false")).lower() == "true":
441 actions.append(action)
442
443 # Set the default action to "abort"
444 if len(actions) == 0:
445 actions.append("abort")
446
447 description = data.get("write-description", None)
448 if description is not None:
449 actions.append("write-description")
450
451 max_restarts = data.get("max-restarts", "0")
452
453 operation_list = XML.SubElement(twrapper, "operationList")
454
455 for action in actions:
456 fmt_str = prefix + "operations.{0}Operation"
457 if action == "abort":
458 XML.SubElement(operation_list, fmt_str.format("Abort"))
459 elif action == "fail":
460 XML.SubElement(operation_list, fmt_str.format("Fail"))
461 elif action == "abort-and-restart":
462 abort_restart = XML.SubElement(
463 operation_list, fmt_str.format("AbortAndRestart")
464 )
465 XML.SubElement(abort_restart, "maxRestarts").text = str(max_restarts)
466 elif action == "write-description":
467 write_description = XML.SubElement(
468 operation_list, fmt_str.format("WriteDescription")
469 )
470 XML.SubElement(write_description, "description").text = description
471 else:
472 raise JenkinsJobsException(
473 "Unsupported BuiltTimeoutWrapper "
474 "plugin action: {0}".format(action)
475 )
476 mapping = [("timeout-var", "timeoutEnvVar", None)]
477 helpers.convert_mapping_to_xml(twrapper, data, mapping, fail_required=False)
478 else:
479 mapping = [
480 ("timeout", "timeoutMinutes", 3),
481 ("timeout-var", "timeoutEnvVar", None),
482 ("fail", "failBuild", "false"),
483 ("write-description", "writingDescription", "false"),
484 ("elastic-percentage", "timeoutPercentage", 0),
485 ("elastic-default-timeout", "timeoutMinutesElasticDefault", 3),
486 ]
487 helpers.convert_mapping_to_xml(twrapper, data, mapping, fail_required=False)
488
489 tout_type = str(data.get("type", "absolute")).lower()
490 if tout_type == "likely-stuck":
491 tout_type = "likelyStuck"
492 XML.SubElement(twrapper, "timeoutType").text = tout_type
493
494
495 def timestamps(registry, xml_parent, data):
496 """yaml: timestamps
497 Add timestamps to the console log.
498
499 Requires the Jenkins :jenkins-plugins:`Timestamper Plugin <timestamper>`.
500
501 Example::
502
503 wrappers:
504 - timestamps
505 """
506 XML.SubElement(xml_parent, "hudson.plugins.timestamper.TimestamperBuildWrapper")
507
508
509 def ansicolor(registry, xml_parent, data):
510 """yaml: ansicolor
511 Translate ANSI color codes to HTML in the console log.
512
513 Requires the Jenkins :jenkins-plugins:`Ansi Color Plugin <ansicolor>`.
514
515 :arg str colormap: Color mapping to use (default xterm)
516
517 Minimal Example:
518
519 .. literalinclude:: /../../tests/wrappers/fixtures/ansicolor-minimal.yaml
520 :language: yaml
521
522 Full Example:
523
524 .. literalinclude:: /../../tests/wrappers/fixtures/ansicolor-full.yaml
525 :language: yaml
526 """
527 cwrapper = XML.SubElement(
528 xml_parent, "hudson.plugins.ansicolor.AnsiColorBuildWrapper"
529 )
530
531 valid_types = ["xterm", "vga", "css", "gnome-terminal"]
532 mapping = [("colormap", "colorMapName", "xterm", valid_types)]
533 helpers.convert_mapping_to_xml(cwrapper, data, mapping, fail_required=False)
534
535
536 def build_keeper(registry, xml_parent, data):
537 """yaml: build-keeper
538 Keep builds based on specific policy.
539
540 Requires the Jenkins :jenkins-plugins:`Build Keeper Plugin
541 <build-keeper-plugin>`.
542
543 :arg str policy: Policy to keep builds.
544
545 :policy values:
546 * **by-day**
547 * **keep-since**
548 * **build-number**
549 * **keep-first-failed**
550 * **run-condition**
551 :arg int build-period: Number argument to calculate build to keep,
552 depends on the policy. (default 0)
553 :arg bool dont-keep-failed: Flag to indicate if to keep failed builds.
554 (default false)
555 :arg int number-of-fails: number of consecutive failed builds in order
556 to mark first as keep forever, only applies to keep-first-failed
557 policy (default 0)
558 :arg bool keep-build: Build will be kept if there is a problem
559 evaluating the RunCondition (default false)
560 :arg str token: Token value for the boolean condition (default '')
561 :arg list build-cause: The cause why the build
562 was triggered (default USER_CAUSE)
563 :arg bool exclusive-cause: Cause must be the only one causing this
564 build to be triggered (default False)
565 :arg str command: Contents of your shell script (default '')
566 :arg str allowed-nodes: Node to be executed on (default '')
567 :arg str expression: The regular expression used to
568 match the label (default '')
569 :arg str label: The label that will be tested by
570 the regular expression (default '')
571 :arg str arg1: First string argument for
572 strings-match condition (default '')
573 :arg str arg2: Second string argument for
574 strings-match condition (default '')
575 :arg bool ignore-case: Ignore the case of the strings when
576 matching the two string arguments (default False)
577
578 Example:
579
580 .. literalinclude:: /../../tests/wrappers/fixtures/build-keeper0001.yaml
581
582 .. literalinclude:: /../../tests/wrappers/fixtures/build-keeper0002.yaml
583
584 """
585 root = XML.SubElement(
586 xml_parent, "org.jenkins__ci.plugins.build__keeper.BuildKeeper"
587 )
588
589 valid_policies = (
590 "by-day",
591 "keep-since",
592 "build-number",
593 "keep-first-failed",
594 "run-condition",
595 )
596 policy = data.get("policy")
597
598 mapping = [
599 ("build-period", "buildPeriod", 0),
600 ("dont-keep-failed", "dontKeepFailed", False),
601 ]
602
603 if policy == "by-day":
604 policy_element = XML.SubElement(
605 root,
606 "policy",
607 {"class": "org.jenkins_ci.plugins." "build_keeper.ByDayPolicy"},
608 )
609 elif policy == "keep-since":
610 policy_element = XML.SubElement(
611 root,
612 "policy",
613 {"class": "org.jenkins_ci.plugins." "build_keeper.KeepSincePolicy"},
614 )
615 elif policy == "build-number":
616 policy_element = XML.SubElement(
617 root,
618 "policy",
619 {"class": "org.jenkins_ci.plugins." "build_keeper.BuildNumberPolicy"},
620 )
621 elif policy == "keep-first-failed":
622 policy_element = XML.SubElement(
623 root,
624 "policy",
625 {"class": "org.jenkins_ci.plugins." "build_keeper.KeepFirstFailedPolicy"},
626 )
627 mapping = [("number-of-fails", "numberOfFails", 0)]
628 elif policy == "run-condition":
629 policy_element = XML.SubElement(
630 root,
631 "policy",
632 {"class": "org.jenkins_ci.plugins." "build_keeper.RunConditionPolicy"},
633 )
634
635 run_condition = data.get("run-condition", [])
636 run_condition_base_class = {
637 "core": "org.jenkins_ci.plugins.run_condition.core.",
638 "shell": "org.jenkins_ci.plugins.run_condition.contributed.",
639 }
640 mapping = [("keep-build", "keepBuildIfEvalFails", False)]
641 bool_cond_mapping = [("token", "token", "")]
642 build_cause_types = [
643 "USER_CAUSE",
644 "CLI_CAUSE",
645 "REMOTE_CAUSE",
646 "SCM_CAUSE",
647 "TIMER_CAUSE",
648 "UPSTREAM_CAUSE",
649 "FS_CAUSE",
650 "URL_CAUSE",
651 "IVY_CAUSE",
652 "SCRIPT_CAUSE",
653 "BUILDRESULT_CAUSE",
654 ]
655 cause_cond_mapping = [
656 ("build-cause", "buildCause", "USER_CAUSE", build_cause_types),
657 ("exclusive-cause", "exclusiveCause", False),
658 ]
659 execute_mapping = [("command", "command", "")]
660 regexp_match_mapping = [
661 ("expression", "expression", ""),
662 ("label", "label", ""),
663 ]
664 strings_match_mapping = [
665 ("arg1", "arg1", ""),
666 ("arg2", "arg2", ""),
667 ("ignore-case", "ignoreCase", False),
668 ]
669 for value in run_condition:
670 if value.get("type") == "always":
671 XML.SubElement(
672 policy_element,
673 "runCondition",
674 {
675 "class": "".join(
676 (run_condition_base_class.get("core"), "AlwaysRun")
677 )
678 },
679 )
680 elif value.get("type") == "never":
681 XML.SubElement(
682 policy_element,
683 "runCondition",
684 {
685 "class": "".join(
686 (run_condition_base_class.get("core"), "NeverRun")
687 )
688 },
689 )
690 elif value.get("type") == "boolean-condition":
691 boolean_condition_element = XML.SubElement(
692 policy_element,
693 "runCondition",
694 {
695 "class": "".join(
696 (run_condition_base_class.get("core"), "BooleanCondition")
697 )
698 },
699 )
700 helpers.convert_mapping_to_xml(
701 boolean_condition_element,
702 value,
703 bool_cond_mapping,
704 fail_required=False,
705 )
706 elif value.get("type") == "cause-condition":
707 cause_condition_element = XML.SubElement(
708 policy_element,
709 "runCondition",
710 {
711 "class": "".join(
712 (run_condition_base_class.get("core"), "CauseCondition")
713 )
714 },
715 )
716 helpers.convert_mapping_to_xml(
717 cause_condition_element,
718 value,
719 cause_cond_mapping,
720 fail_required=False,
721 )
722 elif value.get("type") == "execute-shell":
723 execute_shell_element = XML.SubElement(
724 policy_element,
725 "runCondition",
726 {
727 "class": "".join(
728 (run_condition_base_class.get("shell"), "ShellCondition")
729 )
730 },
731 )
732 helpers.convert_mapping_to_xml(
733 execute_shell_element, value, execute_mapping, fail_required=False
734 )
735 elif value.get("type") == "execute-batch":
736 execute_shell_element = XML.SubElement(
737 policy_element,
738 "runCondition",
739 {
740 "class": "".join(
741 (
742 run_condition_base_class.get("shell"),
743 "BatchFileCondition",
744 )
745 )
746 },
747 )
748 helpers.convert_mapping_to_xml(
749 execute_shell_element, value, execute_mapping, fail_required=False
750 )
751 elif value.get("type") == "execution-node":
752 execute_shell_element = XML.SubElement(
753 policy_element,
754 "runCondition",
755 {
756 "class": "".join(
757 (run_condition_base_class.get("core"), "NodeCondition")
758 )
759 },
760 )
761 allowed_nodes = XML.SubElement(execute_shell_element, "allowedNodes")
762 XML.SubElement(allowed_nodes, "string").text = value.get(
763 "allowed-nodes", None
764 )
765 elif value.get("type") == "regexp-match":
766 regexp_match_element = XML.SubElement(
767 policy_element,
768 "runCondition",
769 {
770 "class": "".join(
771 (
772 run_condition_base_class.get("core"),
773 "ExpressionCondition",
774 )
775 )
776 },
777 )
778 helpers.convert_mapping_to_xml(
779 regexp_match_element,
780 value,
781 regexp_match_mapping,
782 fail_required=False,
783 )
784 elif value.get("type") == "strings-match":
785 strings_match_element = XML.SubElement(
786 policy_element,
787 "runCondition",
788 {
789 "class": "".join(
790 (
791 run_condition_base_class.get("core"),
792 "StringsMatchCondition",
793 )
794 )
795 },
796 )
797 helpers.convert_mapping_to_xml(
798 strings_match_element,
799 value,
800 strings_match_mapping,
801 fail_required=False,
802 )
803 else:
804 InvalidAttributeError("policy", policy, valid_policies)
805
806 helpers.convert_mapping_to_xml(policy_element, data, mapping, fail_required=True)
807
808
809 def live_screenshot(registry, xml_parent, data):
810 """yaml: live-screenshot
811 Show live screenshots of running jobs in the job list.
812
813 Requires the Jenkins :jenkins-plugins:`Live-Screenshot Plugin
814 <livescreenshot>`.
815
816 :arg str full-size: name of screenshot file (default 'screenshot.png')
817 :arg str thumbnail: name of thumbnail file (default 'screenshot-thumb.png')
818
819 File type must be .png and they must be located inside the $WORKDIR.
820
821 Full Example:
822
823 .. literalinclude::
824 /../../tests/wrappers/fixtures/live-screenshot-full.yaml
825
826 Minimal Example:
827
828 .. literalinclude::
829 /../../tests/wrappers/fixtures/live-screenshot-minimal.yaml
830 """
831 live = XML.SubElement(
832 xml_parent, "org.jenkinsci.plugins.livescreenshot.LiveScreenshotBuildWrapper"
833 )
834 live.set("plugin", "livescreenshot")
835 mapping = [
836 ("full-size", "fullscreenFilename", "screenshot.png"),
837 ("thumbnail", "thumbnailFilename", "screenshot-thumb.png"),
838 ]
839 helpers.convert_mapping_to_xml(live, data, mapping, fail_required=True)
840
841
842 def mask_passwords(registry, xml_parent, data):
843 """yaml: mask-passwords
844 Hide passwords in the console log.
845
846 Requires the Jenkins :jenkins-plugins:`Mask Passwords Plugin
847 <mask-passwords>`.
848
849 Example::
850
851 wrappers:
852 - mask-passwords
853 """
854 XML.SubElement(
855 xml_parent,
856 "com.michelin.cio.hudson.plugins.maskpasswords." "MaskPasswordsBuildWrapper",
857 )
858
859
860 def workspace_cleanup(registry, xml_parent, data):
861 """yaml: workspace-cleanup (pre-build)
862
863 Requires the Jenkins :jenkins-plugins:`Workspace Cleanup Plugin
864 <ws-cleanup>`.
865
866 The post-build workspace-cleanup is available as a publisher.
867
868 :arg list include: list of files to be included
869 :arg list exclude: list of files to be excluded
870 :arg bool dirmatch: Apply pattern to directories too (default false)
871 :arg str check-parameter: boolean environment variable to check to
872 determine whether to actually clean up
873 :arg str external-deletion-command: external deletion command to run
874 against files and directories
875 :arg bool disable-deferred-wipeout: Disable improved deferred wipeout
876 method (default false)
877
878 Full Example:
879
880 .. literalinclude::
881 /../../tests/wrappers/fixtures/workspace-cleanup-full.yaml
882 :language: yaml
883
884 Minimal Example:
885
886 .. literalinclude::
887 /../../tests/wrappers/fixtures/workspace-cleanup-min.yaml
888 :language: yaml
889 """
890
891 p = XML.SubElement(xml_parent, "hudson.plugins.ws__cleanup.PreBuildCleanup")
892 p.set("plugin", "ws-cleanup")
893
894 if "include" in data or "exclude" in data:
895 patterns = XML.SubElement(p, "patterns")
896
897 for inc in data.get("include", []):
898 ptrn = XML.SubElement(patterns, "hudson.plugins.ws__cleanup.Pattern")
899 mapping = [("", "pattern", inc), ("", "type", "INCLUDE")]
900 helpers.convert_mapping_to_xml(ptrn, data, mapping, fail_required=True)
901
902 for exc in data.get("exclude", []):
903 ptrn = XML.SubElement(patterns, "hudson.plugins.ws__cleanup.Pattern")
904 mapping = [("", "pattern", exc), ("", "type", "EXCLUDE")]
905 helpers.convert_mapping_to_xml(ptrn, data, mapping, fail_required=True)
906
907 mapping = [
908 ("dirmatch", "deleteDirs", False),
909 ("check-parameter", "cleanupParameter", ""),
910 ("external-deletion-command", "externalDelete", ""),
911 ("disable-deferred-wipeout", "disableDeferredWipeout", False),
912 ]
913 helpers.convert_mapping_to_xml(p, data, mapping, fail_required=True)
914
915
916 def m2_repository_cleanup(registry, xml_parent, data):
917 """yaml: m2-repository-cleanup
918 Configure M2 Repository Cleanup.
919
920 Requires the Jenkins :jenkins-plugins:`M2 Repository Cleanup
921 <maven-repo-cleaner>`.
922
923 :arg list patterns: List of patterns for artifacts to cleanup before
924 building. (optional)
925
926 This plugin allows you to configure a maven2 job to clean some or all of
927 the artifacts from the repository before it runs.
928
929 Example:
930
931 .. literalinclude:: \
932 ../../tests/wrappers/fixtures/m2-repository-cleanup001.yaml
933 """
934 m2repo = XML.SubElement(
935 xml_parent, "hudson.plugins.m2__repo__reaper.M2RepoReaperWrapper"
936 )
937 m2repo.set("plugin", "m2-repo-reaper")
938 patterns = data.get("patterns", [])
939 XML.SubElement(m2repo, "artifactPatterns").text = ",".join(patterns)
940 p = XML.SubElement(m2repo, "patterns")
941 for pattern in patterns:
942 XML.SubElement(p, "string").text = pattern
943
944
945 def rvm_env(registry, xml_parent, data):
946 """yaml: rvm-env
947 Set the RVM implementation.
948
949 Requires the Jenkins :jenkins-plugins:`Rvm Plugin <rvm>`.
950
951 :arg str implementation: Type of implementation. Syntax is RUBY[@GEMSET],
952 such as '1.9.3' or 'jruby@foo'.
953
954 Example::
955
956 wrappers:
957 - rvm-env:
958 implementation: 1.9.3
959 """
960 rpo = XML.SubElement(xml_parent, "ruby-proxy-object")
961
962 ro_class = "Jenkins::Plugin::Proxies::BuildWrapper"
963
964 plugin_ver = registry.get_plugin_version("RVM Plugin")
965
966 if plugin_ver >= "0.5":
967 ro_class = "Jenkins::Tasks::BuildWrapperProxy"
968
969 ro = XML.SubElement(rpo, "ruby-object", {"ruby-class": ro_class, "pluginid": "rvm"})
970
971 o = XML.SubElement(ro, "object", {"ruby-class": "RvmWrapper", "pluginid": "rvm"})
972
973 XML.SubElement(o, "impl", {"pluginid": "rvm", "ruby-class": "String"}).text = data[
974 "implementation"
975 ]
976
977 XML.SubElement(
978 ro, "pluginid", {"pluginid": "rvm", "ruby-class": "String"}
979 ).text = "rvm"
980
981
982 def rbenv(registry, xml_parent, data):
983 """yaml: rbenv
984 Set the rbenv implementation.
985
986 Requires the Jenkins :jenkins-plugins:`rbenv plugin <rbenv>`.
987
988 All parameters are optional.
989
990 :arg str ruby-version: Version of Ruby to use (default 1.9.3-p484)
991 :arg bool ignore-local-version: If true, ignore local Ruby
992 version (defined in the ".ruby-version" file in workspace) even if it
993 has been defined (default false)
994 :arg str preinstall-gem-list: List of gems to install
995 (default 'bundler,rake')
996 :arg str rbenv-root: RBENV_ROOT (default $HOME/.rbenv)
997 :arg str rbenv-repo: Which repo to clone rbenv from
998 (default https://github.com/rbenv/rbenv)
999 :arg str rbenv-branch: Which branch to clone rbenv from (default master)
1000 :arg str ruby-build-repo: Which repo to clone ruby-build from
1001 (default https://github.com/rbenv/ruby-build)
1002 :arg str ruby-build-branch: Which branch to clone ruby-build from
1003 (default master)
1004
1005 Example:
1006
1007 .. literalinclude:: /../../tests/wrappers/fixtures/rbenv003.yaml
1008 """
1009
1010 rpo = XML.SubElement(xml_parent, "ruby-proxy-object")
1011
1012 ro_class = "Jenkins::Tasks::BuildWrapperProxy"
1013 ro = XML.SubElement(
1014 rpo, "ruby-object", {"pluginid": "rbenv", "ruby-class": ro_class}
1015 )
1016
1017 XML.SubElement(
1018 ro, "pluginid", {"pluginid": "rbenv", "ruby-class": "String"}
1019 ).text = "rbenv"
1020
1021 o = XML.SubElement(
1022 ro, "object", {"pluginid": "rbenv", "ruby-class": "RbenvWrapper"}
1023 )
1024
1025 mapping = [
1026 # option, xml name, default value (text), attributes (hard coded)
1027 ("preinstall-gem-list", "gem__list", "bundler,rake"),
1028 ("rbenv-root", "rbenv__root", "$HOME/.rbenv"),
1029 ("rbenv-repo", "rbenv__repository", "https://github.com/rbenv/rbenv"),
1030 ("rbenv-branch", "rbenv__revision", "master"),
1031 (
1032 "ruby-build-repo",
1033 "ruby__build__repository",
1034 "https://github.com/rbenv/ruby-build",
1035 ),
1036 ("ruby-build-branch", "ruby__build__revision", "master"),
1037 ("ruby-version", "version", "1.9.3-p484"),
1038 ]
1039 helpers.convert_mapping_to_xml(o, data, mapping, fail_required=False)
1040
1041 for elem in mapping:
1042 (optname, xmlname, val) = elem[:3]
1043 elem_tag = o.find(xmlname)
1044 elem_tag.set("pluginid", "rbenv")
1045 elem_tag.set("ruby-class", "String")
1046
1047 ignore_local_class = "FalseClass"
1048
1049 if "ignore-local-version" in data:
1050 ignore_local_string = str(data["ignore-local-version"]).lower()
1051 if ignore_local_string == "true":
1052 ignore_local_class = "TrueClass"
1053
1054 XML.SubElement(
1055 o,
1056 "ignore__local__version",
1057 {"pluginid": "rbenv", "ruby-class": ignore_local_class},
1058 )
1059
1060
1061 def build_name(registry, xml_parent, data):
1062 """yaml: build-name
1063 Set the name of the build.
1064
1065 Requires the Jenkins :jenkins-plugins:`Build Name Setter Plugin
1066 <build-name-setter>`.
1067
1068 :arg str name: Name for the build. Typically you would use a variable
1069 from Jenkins in the name. The syntax would be ${FOO} for
1070 the FOO variable.
1071 :arg str description: Build description for the build (Optional).
1072 :arg str run-at-start: Set build name before build starts (Optional, default: True).
1073 :arg str run-at-end: Set build name after build ends (Optional, default: True).
1074
1075 Example::
1076
1077 wrappers:
1078 - build-name:
1079 name: Build-${FOO}
1080 description: lorem ipsum dolor
1081 run-at-start: true
1082 run-at-end: false
1083 """
1084 bsetter = XML.SubElement(
1085 xml_parent, "org.jenkinsci.plugins.buildnamesetter." "BuildNameSetter"
1086 )
1087 mapping = [
1088 ("name", "template", None),
1089 ("description", "descriptionTemplate", ""),
1090 ("run-at-start", "runAtStart", True),
1091 ("run-at-end", "runAtEnd", True),
1092 ]
1093 helpers.convert_mapping_to_xml(bsetter, data, mapping, fail_required=True)
1094
1095
1096 def port_allocator(registry, xml_parent, data):
1097 """yaml: port-allocator
1098 Assign unique TCP port numbers.
1099
1100 Requires the Jenkins :jenkins-plugins:`Port Allocator Plugin
1101 <port-allocator>`.
1102
1103 :arg str name: Deprecated, use names instead
1104 :arg list names: Variable list of names of the port or list of
1105 specific port numbers
1106
1107 Example:
1108
1109 .. literalinclude:: /../../tests/wrappers/fixtures/port-allocator002.yaml
1110 """
1111 pa = XML.SubElement(
1112 xml_parent, "org.jvnet.hudson.plugins.port__allocator." "PortAllocator"
1113 )
1114 ports = XML.SubElement(pa, "ports")
1115 names = data.get("names")
1116 if not names:
1117 logger = logging.getLogger(__name__)
1118 logger.warning(
1119 "port_allocator name is deprecated, use a names list " " instead"
1120 )
1121 names = [data["name"]]
1122 for name in names:
1123 dpt = XML.SubElement(
1124 ports, "org.jvnet.hudson.plugins.port__allocator." "DefaultPortType"
1125 )
1126 XML.SubElement(dpt, "name").text = name
1127
1128
1129 def locks(registry, xml_parent, data):
1130 """yaml: locks
1131 Control parallel execution of jobs.
1132
1133 Requires the Jenkins :jenkins-github:`Locks and Latches Plugin
1134 <locks-and-latches-plugin>`.
1135
1136 :arg: list of locks to use
1137
1138 Example:
1139
1140 .. literalinclude:: /../../tests/wrappers/fixtures/locks002.yaml
1141 :language: yaml
1142 """
1143 locks = data
1144 if locks:
1145 lw = XML.SubElement(xml_parent, "hudson.plugins.locksandlatches.LockWrapper")
1146 locktop = XML.SubElement(lw, "locks")
1147 for lock in locks:
1148 lockwrapper = XML.SubElement(
1149 locktop, "hudson.plugins.locksandlatches." "LockWrapper_-LockWaitConfig"
1150 )
1151 XML.SubElement(lockwrapper, "name").text = lock
1152
1153
1154 def copy_to_slave(registry, xml_parent, data):
1155 """yaml: copy-to-slave
1156 Copy files to slave before build.
1157
1158 Requires the Jenkins :jenkins-plugins:`Copy To Slave Plugin <copy-to-slave>`.
1159
1160 :arg list includes: list of file patterns to copy (optional)
1161 :arg list excludes: list of file patterns to exclude (optional)
1162 :arg bool flatten: flatten directory structure (default false)
1163 :arg str relative-to: base location of includes/excludes, must be home
1164 ($JENKINS_HOME), somewhereElse ($JENKINS_HOME/copyToSlave),
1165 userContent ($JENKINS_HOME/userContent) or workspace
1166 (default userContent)
1167 :arg bool include-ant-excludes: exclude ant's default excludes
1168 (default false)
1169
1170 Minimal Example:
1171
1172 .. literalinclude:: /../../tests/wrappers/fixtures/copy-to-slave001.yaml
1173 :language: yaml
1174
1175 Full Example:
1176
1177 .. literalinclude:: /../../tests/wrappers/fixtures/copy-to-slave002.yaml
1178 :language: yaml
1179 """
1180 p = "com.michelin.cio.hudson.plugins.copytoslave.CopyToSlaveBuildWrapper"
1181 cs = XML.SubElement(xml_parent, p)
1182
1183 XML.SubElement(cs, "includes").text = ",".join(data.get("includes", [""]))
1184 XML.SubElement(cs, "excludes").text = ",".join(data.get("excludes", [""]))
1185
1186 locations = ["home", "somewhereElse", "userContent", "workspace"]
1187 mapping = [
1188 ("flatten", "flatten", False),
1189 ("include-ant-excludes", "includeAntExcludes", False),
1190 ("relative-to", "relativeTo", "userContent", locations),
1191 ("", "hudsonHomeRelative", False),
1192 ]
1193 helpers.convert_mapping_to_xml(cs, data, mapping, fail_required=True)
1194
1195
1196 def inject(registry, xml_parent, data):
1197 """yaml: inject
1198 Add or override environment variables to the whole build process.
1199
1200 Requires the Jenkins :jenkins-plugins:`EnvInject Plugin <envinject>`.
1201
1202 :arg str properties-file: path to the properties file (optional)
1203 :arg str properties-content: key value pair of properties (optional)
1204 :arg str script-file: path to the script file (optional)
1205 :arg str script-content: contents of a script (optional)
1206 :arg bool load-from-master: load files from master (default false)
1207 :arg str groovy-script: contents of the groovy script (optional)
1208 :arg bool groovy-sandbox: use groovy sandbox (default false)
1209
1210 Minimal Example:
1211
1212 .. literalinclude:: /../../tests/wrappers/fixtures/inject-minimal.yaml
1213
1214 Full Example:
1215
1216 .. literalinclude:: /../../tests/wrappers/fixtures/inject-full.yaml
1217
1218 """
1219 eib = XML.SubElement(xml_parent, "EnvInjectBuildWrapper")
1220 info = XML.SubElement(eib, "info")
1221 mapping = [
1222 ("properties-file", "propertiesFilePath", None),
1223 ("properties-content", "propertiesContent", None),
1224 ("script-file", "scriptFilePath", None),
1225 ("script-content", "scriptContent", None),
1226 ("load-from-master", "loadFilesFromMaster", False),
1227 ]
1228 helpers.convert_mapping_to_xml(info, data, mapping, fail_required=False)
1229
1230 secure_groovy_script = XML.SubElement(info, "secureGroovyScript")
1231 mapping = [("groovy-script", "script", None), ("groovy-sandbox", "sandbox", False)]
1232 helpers.convert_mapping_to_xml(
1233 secure_groovy_script, data, mapping, fail_required=False
1234 )
1235
1236
1237 def inject_ownership_variables(registry, xml_parent, data):
1238 """yaml: inject-ownership-variables
1239 Inject ownership variables to the build as environment variables.
1240
1241 Requires the Jenkins :jenkins-plugins:`EnvInject Plugin <envinject>`
1242 and Jenkins :jenkins-plugins:`Ownership plugin <ownership>`.
1243
1244 :arg bool job-variables: inject job ownership variables to the job
1245 (default false)
1246 :arg bool node-variables: inject node ownership variables to the job
1247 (default false)
1248
1249 Example:
1250
1251 .. literalinclude:: /../../tests/wrappers/fixtures/ownership001.yaml
1252
1253 """
1254 ownership = XML.SubElement(
1255 xml_parent,
1256 "com.synopsys.arc.jenkins.plugins." "ownership.wrappers.OwnershipBuildWrapper",
1257 )
1258 mapping = [
1259 ("node-variables", "injectNodeOwnership", False),
1260 ("job-variables", "injectJobOwnership", False),
1261 ]
1262 helpers.convert_mapping_to_xml(ownership, data, mapping, fail_required=True)
1263
1264
1265 def inject_passwords(registry, xml_parent, data):
1266 """yaml: inject-passwords
1267 Inject passwords to the build as environment variables.
1268
1269 Requires the Jenkins :jenkins-plugins:`EnvInject Plugin <envinject>`.
1270
1271 :arg bool global: inject global passwords to the job
1272 :arg bool mask-password-params: mask password parameters
1273 :arg list job-passwords: key value pair of job passwords
1274
1275 :Parameter: * **name** (`str`) Name of password
1276 * **password** (`str`) Encrypted password
1277
1278 Example:
1279
1280 .. literalinclude:: /../../tests/wrappers/fixtures/passwords001.yaml
1281
1282 """
1283 eib = XML.SubElement(xml_parent, "EnvInjectPasswordWrapper")
1284 mapping = [
1285 ("global", "injectGlobalPasswords", False),
1286 ("mask-password-params", "maskPasswordParameters", False),
1287 ]
1288 helpers.convert_mapping_to_xml(eib, data, mapping, fail_required=True)
1289
1290 entries = XML.SubElement(eib, "passwordEntries")
1291 passwords = data.get("job-passwords", [])
1292 if passwords:
1293 for password in passwords:
1294 entry = XML.SubElement(entries, "EnvInjectPasswordEntry")
1295 mapping = [("name", "name", None), ("password", "value", None)]
1296 helpers.convert_mapping_to_xml(entry, password, mapping, fail_required=True)
1297
1298
1299 def vault_secrets(registry, xml_parent, data):
1300 """yaml: vault-secrets
1301 Inject environment variables from a HashiCorp Vault secret.
1302
1303 Secrets are generally masked in the build log.
1304
1305 Requires the Jenkins :jenkins-plugins:`HashiCorp Vault Plugin
1306 <hashicorp-vault-plugin>`.
1307
1308 :arg str vault-url: Vault URL
1309 :arg str credentials-id: Vault Credential
1310 :arg str engine-version: Vault K/V Engine version
1311 :arg bool fail-if-not-found: Fail if the secret path is not found
1312 :arg bool skip-ssl-verification: Skip verification of SSL certs
1313 :arg list secrets: List of secrets
1314
1315 :secrets:
1316 * **secret-path** (`str`) --
1317 The path of the secret in the vault server
1318 * **engine-version** (`str`) --
1319 Vault K/V Engine version
1320
1321 :secret-values:
1322 * **secret-values** (`list`) -- List of key / value pairs
1323
1324 * **env-var** (`str`) --
1325 The environment variable to set with the value of the
1326 vault key
1327 * **vault-key** (`str`) -- The vault key whose value with
1328 populate the environment variable
1329
1330 Minimal Example:
1331
1332 .. literalinclude:: /../../tests/wrappers/fixtures/vault-minimal.yaml
1333 :language: yaml
1334
1335 Full Example:
1336
1337 .. literalinclude:: /../../tests/wrappers/fixtures/vault-full.yaml
1338 :language: yaml
1339
1340 """
1341 vault = XML.SubElement(xml_parent, "com.datapipe.jenkins.vault.VaultBuildWrapper")
1342 vault.set("plugin", "hashicorp-vault-plugin")
1343 configuration = XML.SubElement(vault, "configuration")
1344 conf_mapping = [
1345 ("vault-url", "vaultUrl", ""),
1346 ("credentials-id", "vaultCredentialId", ""),
1347 ("engine-version", "engineVersion", "1"),
1348 ("fail-if-not-found", "failIfNotFound", "true"),
1349 ("skip-ssl-verification", "skipSslVerification", "false"),
1350 ]
1351 helpers.convert_mapping_to_xml(
1352 configuration, data, conf_mapping, fail_required=True
1353 )
1354
1355 secret_obj_mapping = [
1356 ("secret-path", "path", ""),
1357 ("engine-version", "engineVersion", "1"),
1358 ]
1359 secret_value_mapping = [("env-var", "envVar", ""), ("vault-key", "vaultKey", "")]
1360 secretsobj = XML.SubElement(vault, "vaultSecrets")
1361 secrets = data.get("secrets", [])
1362 for secret in secrets:
1363 secretobj = XML.SubElement(
1364 secretsobj, "com.datapipe.jenkins.vault.model.VaultSecret"
1365 )
1366
1367 helpers.convert_mapping_to_xml(
1368 secretobj, secret, secret_obj_mapping, fail_required=False
1369 )
1370 secretvaluesobj = XML.SubElement(secretobj, "secretValues")
1371 for secretvalue in secret["secret-values"]:
1372 secretvalueobj = XML.SubElement(
1373 secretvaluesobj, "com.datapipe.jenkins.vault.model.VaultSecretValue"
1374 )
1375 helpers.convert_mapping_to_xml(
1376 secretvalueobj, secretvalue, secret_value_mapping, fail_required=False
1377 )
1378 XML.SubElement(vault, "valuesToMask")
1379 XML.SubElement(vault, "vaultAccessor")
1380
1381
1382 def env_file(registry, xml_parent, data):
1383 """yaml: env-file
1384 Add or override environment variables to the whole build process.
1385
1386 Requires the Jenkins :jenkins-plugins:`Environment File Plugin <envfile>`.
1387
1388 :arg str properties-file: path to the properties file (optional)
1389
1390 Example::
1391
1392 wrappers:
1393 - env-file:
1394 properties-file: ${WORKSPACE}/foo
1395 """
1396 eib = XML.SubElement(xml_parent, "hudson.plugins.envfile.EnvFileBuildWrapper")
1397 mapping = [("properties-file", "filePath", None)]
1398 helpers.convert_mapping_to_xml(eib, data, mapping, fail_required=False)
1399
1400
1401 def env_script(registry, xml_parent, data):
1402 """yaml: env-script
1403 Add or override environment variables to the whole build process.
1404
1405 Requires the Jenkins :jenkins-plugins:`Environment Script Plugin
1406 <environment-script>`.
1407
1408 :arg script-content: The script to run (default '')
1409 :arg str script-type: The script type.
1410
1411 :script-types supported:
1412 * **unix-script** (default)
1413 * **power-shell**
1414 * **batch-script**
1415 :arg only-run-on-parent: Only applicable for Matrix Jobs. If true, run only
1416 on the matrix parent job (default false)
1417
1418 Example:
1419
1420 .. literalinclude:: /../../tests/wrappers/fixtures/env-script001.yaml
1421
1422 """
1423 el = XML.SubElement(xml_parent, "com.lookout.jenkins.EnvironmentScript")
1424
1425 valid_script_types = {
1426 "unix-script": "unixScript",
1427 "power-shell": "powerShell",
1428 "batch-script": "batchScript",
1429 }
1430 mapping = [
1431 ("script-content", "script", ""),
1432 ("script-type", "scriptType", "unix-script", valid_script_types),
1433 ("only-run-on-parent", "runOnlyOnParent", False),
1434 ]
1435 helpers.convert_mapping_to_xml(el, data, mapping, fail_required=True)
1436
1437
1438 def jclouds(registry, xml_parent, data):
1439 """yaml: jclouds
1440 Uses JClouds to provide slave launching on most of the currently
1441 usable Cloud infrastructures.
1442
1443 Requires the Jenkins :jenkins-plugins:`JClouds Plugin <jclouds-jenkins>`.
1444
1445 :arg bool single-use: Whether or not to terminate the slave after use
1446 (default false).
1447 :arg list instances: The name of the jclouds template to create an
1448 instance from, and its parameters.
1449 :arg str cloud-name: The name of the jclouds profile containing the
1450 specified template.
1451 :arg int count: How many instances to create (default 1).
1452 :arg bool stop-on-terminate: Whether or not to suspend instead of terminate
1453 the instance (default false).
1454
1455 Example:
1456
1457 .. literalinclude:: /../../tests/wrappers/fixtures/jclouds001.yaml
1458 :language: yaml
1459
1460 """
1461 mapping = [
1462 ("cloud-name", "cloudName", ""),
1463 ("count", "count", "1"),
1464 ("stop-on-terminate", "suspendOrTerminate", False),
1465 ]
1466 if "instances" in data:
1467 buildWrapper = XML.SubElement(
1468 xml_parent, "jenkins.plugins.jclouds.compute.JCloudsBuildWrapper"
1469 )
1470 instances = XML.SubElement(buildWrapper, "instancesToRun")
1471 for foo in data["instances"]:
1472 for template, params in foo.items():
1473 instance = XML.SubElement(
1474 instances, "jenkins.plugins.jclouds.compute." "InstancesToRun"
1475 )
1476 XML.SubElement(instance, "templateName").text = template
1477 helpers.convert_mapping_to_xml(
1478 instance, params, mapping, fail_required=False
1479 )
1480 if data.get("single-use"):
1481 XML.SubElement(
1482 xml_parent, "jenkins.plugins.jclouds.compute." "JCloudsOneOffSlave"
1483 )
1484
1485
1486 def openstack(registry, xml_parent, data):
1487 """yaml: openstack
1488 Provision slaves from OpenStack on demand.
1489
1490 Requires the Jenkins :jenkins-plugins:`Openstack Cloud Plugin
1491 <openstack-cloud>`.
1492
1493 :arg list instances: List of instances to be launched at the beginning of
1494 the build.
1495
1496 :instances:
1497 * **cloud-name** (`str`) -- The name of the cloud profile which
1498 contains the specified cloud instance template (required).
1499 * **template-name** (`str`) -- The name of the cloud instance
1500 template to create an instance from(required).
1501 * **manual-template** (`bool`) -- If True, instance template name
1502 will be put in 'Specify Template Name as String' option. Not
1503 specifying or specifying False, instance template name will be
1504 put in 'Select Template from List' option. To use parameter
1505 replacement, set this to True. (default false)
1506 * **count** (`int`) -- How many instances to create (default 1).
1507
1508 :arg bool single-use: Whether or not to terminate the slave after use
1509 (default false).
1510
1511 Example:
1512
1513 .. literalinclude:: /../../tests/wrappers/fixtures/openstack001.yaml
1514 """
1515 tag_prefix = "jenkins.plugins.openstack.compute."
1516
1517 if "instances" in data:
1518 clouds_build_wrapper = XML.SubElement(
1519 xml_parent, tag_prefix + "JCloudsBuildWrapper"
1520 )
1521 instances_wrapper = XML.SubElement(clouds_build_wrapper, "instancesToRun")
1522
1523 for instance in data["instances"]:
1524 instances_to_run = XML.SubElement(
1525 instances_wrapper, tag_prefix + "InstancesToRun"
1526 )
1527
1528 instance_mapping = [
1529 ("cloud-name", "cloudName", None),
1530 ("count", "count", 1),
1531 ]
1532
1533 if instance.get("manual-template", False):
1534 instance_mapping.append(("template-name", "manualTemplateName", None))
1535 else:
1536 instance_mapping.append(("template-name", "templateName", None))
1537 helpers.convert_mapping_to_xml(
1538 instances_to_run, instance, instance_mapping, fail_required=True
1539 )
1540
1541 if data.get("single-use", False):
1542 XML.SubElement(xml_parent, tag_prefix + "JCloudsOneOffSlave")
1543
1544
1545 def build_user_vars(registry, xml_parent, data):
1546 """yaml: build-user-vars
1547 Set environment variables to the value of the user that started the build.
1548
1549 Requires the Jenkins :jenkins-plugins:`Build User Vars Plugin
1550 <build-user-vars-plugin>`.
1551
1552 Example::
1553
1554 wrappers:
1555 - build-user-vars
1556 """
1557 XML.SubElement(xml_parent, "org.jenkinsci.plugins.builduser.BuildUser")
1558
1559
1560 def release(registry, xml_parent, data):
1561 """yaml: release
1562 Add release build configuration.
1563
1564 Requires the Jenkins :jenkins-plugins:`Release Plugin <release>`.
1565
1566 :arg bool keep-forever: Keep build forever (default true)
1567 :arg bool override-build-parameters: Enable build-parameter override
1568 (default false)
1569 :arg str version-template: Release version template (default '')
1570 :arg list parameters: Release parameters (see the :ref:`Parameters` module)
1571 :arg list pre-build: Pre-build steps (see the :ref:`Builders` module)
1572 :arg list post-build: Post-build steps (see :ref:`Builders`)
1573 :arg list post-success: Post successful-build steps (see :ref:`Builders`)
1574 :arg list post-failed: Post failed-build steps (see :ref:`Builders`)
1575
1576 Example:
1577
1578 .. literalinclude:: /../../tests/wrappers/fixtures/release001.yaml
1579
1580 """
1581 relwrap = XML.SubElement(xml_parent, "hudson.plugins.release.ReleaseWrapper")
1582 # For 'keep-forever', the sense of the XML flag is the opposite of
1583 # the YAML flag.
1584 mapping = [
1585 ("do-not-keep-log", "doNotKeepLog", not data.get("keep-forever", True)),
1586 ("override-build-parameters", "overrideBuildParameters", False),
1587 ("version-template", "releaseVersionTemplate", ""),
1588 ]
1589 helpers.convert_mapping_to_xml(relwrap, data, mapping, fail_required=True)
1590
1591 parameters = data.get("parameters", [])
1592 if parameters:
1593 pdef = XML.SubElement(relwrap, "parameterDefinitions")
1594 for param in parameters:
1595 registry.dispatch("parameter", pdef, param)
1596 builder_steps = {
1597 "pre-build": "preBuildSteps",
1598 "post-build": "postBuildSteps",
1599 "post-success": "postSuccessfulBuildSteps",
1600 "post-fail": "postFailedBuildSteps",
1601 }
1602 for step in builder_steps.keys():
1603 for builder in data.get(step, []):
1604 registry.dispatch(
1605 "builder", XML.SubElement(relwrap, builder_steps[step]), builder
1606 )
1607
1608
1609 def sauce_ondemand(registry, xml_parent, data):
1610 """yaml: sauce-ondemand
1611 Allows you to integrate Sauce OnDemand with Jenkins. You can
1612 automate the setup and tear down of Sauce Connect and integrate
1613 the Sauce OnDemand results videos per test.
1614
1615 Requires the Jenkins :jenkins-plugins:`Sauce OnDemand Plugin
1616 <sauce-ondemand>`.
1617
1618 :arg bool enable-sauce-connect: launches a SSH tunnel from their cloud
1619 to your private network (default false)
1620 :arg str sauce-host: The name of the selenium host to be used. For
1621 tests run using Sauce Connect, this should be localhost.
1622 ondemand.saucelabs.com can also be used to connect directly to
1623 Sauce OnDemand, The value of the host will be stored in the
1624 SAUCE_ONDEMAND_HOST environment variable. (default '')
1625 :arg str sauce-port: The name of the Selenium Port to be used. For
1626 tests run using Sauce Connect, this should be 4445. If using
1627 ondemand.saucelabs.com for the Selenium Host, then use 4444.
1628 The value of the port will be stored in the SAUCE_ONDEMAND_PORT
1629 environment variable. (default '')
1630 :arg str override-username: If set then api-access-key must be set.
1631 Overrides the username from the global config. (default '')
1632 :arg str override-api-access-key: If set then username must be set.
1633 Overrides the api-access-key set in the global config. (default '')
1634 :arg str starting-url: The value set here will be stored in the
1635 SELENIUM_STARTING_ULR environment variable. Only used when type
1636 is selenium. (default '')
1637 :arg str type: Type of test to run (default selenium)
1638
1639 :type values:
1640 * **selenium**
1641 * **webdriver**
1642 :arg list platforms: The platforms to run the tests on. Platforms
1643 supported are dynamically retrieved from sauce labs. The format of
1644 the values has only the first letter capitalized, no spaces, underscore
1645 between os and version, underscore in internet_explorer, everything
1646 else is run together. If there are not multiple version of the browser
1647 then just the first version number is used.
1648 Examples: Mac_10.8iphone5.1 or Windows_2003firefox10
1649 or Windows_2012internet_explorer10 (default '')
1650 :arg bool launch-sauce-connect-on-slave: Whether to launch sauce connect
1651 on the slave. (default false)
1652 :arg str https-protocol: The https protocol to use (default '')
1653 :arg str sauce-connect-options: Options to pass to sauce connect
1654 (default '')
1655
1656 Example::
1657
1658 wrappers:
1659 - sauce-ondemand:
1660 enable-sauce-connect: true
1661 sauce-host: foo
1662 sauce-port: 8080
1663 override-username: foo
1664 override-api-access-key: 123lkj123kh123l;k12323
1665 type: webdriver
1666 platforms:
1667 - Linuxandroid4
1668 - Linuxfirefox10
1669 - Linuxfirefox11
1670 launch-sauce-connect-on-slave: true
1671 """
1672 sauce = XML.SubElement(
1673 xml_parent, "hudson.plugins.sauce__ondemand." "SauceOnDemandBuildWrapper"
1674 )
1675 mapping = [
1676 ("enable-sauce-connect", "enableSauceConnect", False),
1677 ("sauce-host", "seleniumHost", ""),
1678 ("sauce-port", "seleniumPort", ""),
1679 ("launch-sauce-connect-on-slave", "launchSauceConnectOnSlave", False),
1680 ("https-protocol", "httpsProtocol", ""),
1681 ("sauce-connect-options", "options", ""),
1682 ]
1683 helpers.convert_mapping_to_xml(sauce, data, mapping, fail_required=True)
1684
1685 # Optional override global authentication
1686 username = data.get("override-username")
1687 key = data.get("override-api-access-key")
1688 if username and key:
1689 cred = XML.SubElement(sauce, "credentials")
1690 mapping = [
1691 ("override-username", "username", None),
1692 ("override-api-access-key", "apiKey", None),
1693 ]
1694 helpers.convert_mapping_to_xml(cred, data, mapping, fail_required=True)
1695 atype = data.get("type", "selenium")
1696 info = XML.SubElement(sauce, "seleniumInformation")
1697
1698 if atype == "selenium":
1699 selenium_mapping = [
1700 ("starting-url", "seleniumBrowsers", ""),
1701 ("", "isWebDriver", False),
1702 ]
1703 helpers.convert_mapping_to_xml(info, data, selenium_mapping, fail_required=True)
1704
1705 browsers = XML.SubElement(info, "seleniumBrowsers")
1706 for platform in data["platforms"]:
1707 mapping = [("", "string", platform)]
1708 helpers.convert_mapping_to_xml(browsers, data, mapping, fail_required=True)
1709 XML.SubElement(
1710 sauce,
1711 "seleniumBrowsers",
1712 {"reference": "../seleniumInformation/" "seleniumBrowsers"},
1713 )
1714 if atype == "webdriver":
1715 browsers = XML.SubElement(info, "webDriverBrowsers")
1716 for platform in data["platforms"]:
1717 mapping = [("", "string", platform)]
1718 helpers.convert_mapping_to_xml(browsers, data, mapping, fail_required=True)
1719 webdriver_mapping = [("", "isWebDriver", True)]
1720 helpers.convert_mapping_to_xml(
1721 info, data, webdriver_mapping, fail_required=True
1722 )
1723 XML.SubElement(
1724 sauce,
1725 "webDriverBrowsers",
1726 {"reference": "../seleniumInformation/" "webDriverBrowsers"},
1727 )
1728
1729
1730 def sonar(registry, xml_parent, data):
1731 """yaml: sonar
1732 Wrapper for SonarQube Plugin.
1733
1734 Requires :jenkins-plugins:`SonarQube plugin <sonar>`
1735
1736 :arg str install-name: Release goals and options (default '')
1737
1738 Minimal Example:
1739
1740 .. literalinclude:: /../../tests/wrappers/fixtures/sonar-minimal.yaml
1741 :language: yaml
1742
1743 Full Example:
1744
1745 .. literalinclude:: /../../tests/wrappers/fixtures/sonar-full.yaml
1746 :language: yaml
1747 """
1748 sonar = XML.SubElement(xml_parent, "hudson.plugins.sonar.SonarBuildWrapper")
1749 sonar.set("plugin", "sonar")
1750
1751 if data.get("install-name"):
1752 mapping = [("install-name", "installationName", "")]
1753 helpers.convert_mapping_to_xml(sonar, data, mapping, fail_required=True)
1754
1755
1756 def pathignore(registry, xml_parent, data):
1757 """yaml: pathignore
1758 This plugin allows SCM-triggered jobs to ignore
1759 build requests if only certain paths have changed.
1760
1761 Requires the Jenkins :jenkins-plugins:`Pathignore Plugin <pathignore>`.
1762
1763 :arg str ignored: A set of patterns to define ignored changes
1764
1765 Example::
1766
1767 wrappers:
1768 - pathignore:
1769 ignored: "docs, tests"
1770 """
1771 ruby = XML.SubElement(xml_parent, "ruby-proxy-object")
1772 robj = XML.SubElement(
1773 ruby,
1774 "ruby-object",
1775 attrib={
1776 "pluginid": "pathignore",
1777 "ruby-class": "Jenkins::Plugin::Proxies::BuildWrapper",
1778 },
1779 )
1780 pluginid = XML.SubElement(
1781 robj, "pluginid", {"pluginid": "pathignore", "ruby-class": "String"}
1782 )
1783 pluginid.text = "pathignore"
1784 obj = XML.SubElement(
1785 robj, "object", {"ruby-class": "PathignoreWrapper", "pluginid": "pathignore"}
1786 )
1787 ignored = XML.SubElement(
1788 obj, "ignored__paths", {"pluginid": "pathignore", "ruby-class": "String"}
1789 )
1790 ignored.text = data.get("ignored", "")
1791 XML.SubElement(
1792 obj, "invert__ignore", {"ruby-class": "FalseClass", "pluginid": "pathignore"}
1793 )
1794
1795
1796 def pre_scm_buildstep(registry, xml_parent, data):
1797 """yaml: pre-scm-buildstep
1798 Execute a Build Step before running the SCM.
1799
1800 Requires the Jenkins :jenkins-plugins:`Pre SCM BuildStep
1801 <preSCMbuildstep>`.
1802
1803 :arg str failOnError: Specifies if the job should fail on error
1804 (plugin >= 0.3) (default false).
1805 :arg list buildsteps: List of build steps to execute
1806
1807 :Buildstep: Any acceptable builder, as seen in the example
1808
1809 Example:
1810
1811 .. literalinclude::
1812 /../../tests/wrappers/fixtures/pre-scm-buildstep001.yaml
1813 :language: yaml
1814 """
1815 # Get plugin information to maintain backwards compatibility
1816 plugin_ver = registry.get_plugin_version("preSCMbuildstep")
1817
1818 bsp = XML.SubElement(
1819 xml_parent, "org.jenkinsci.plugins.preSCMbuildstep." "PreSCMBuildStepsWrapper"
1820 )
1821 bs = XML.SubElement(bsp, "buildSteps")
1822 stepList = data if isinstance(data, list) else data.get("buildsteps")
1823
1824 for step in stepList:
1825 for edited_node in create_builders(registry, step):
1826 bs.append(edited_node)
1827 if plugin_ver >= "0.3" and not isinstance(data, list):
1828 mapping = [("failOnError", "failOnError", False)]
1829 helpers.convert_mapping_to_xml(bsp, data, mapping, fail_required=True)
1830
1831
1832 def logstash(registry, xml_parent, data):
1833 """yaml: logstash build wrapper
1834 Dump the Jenkins console output to Logstash.
1835
1836 Requires the Jenkins :jenkins-plugins:`logstash plugin <logstash>`.
1837
1838 :arg use-redis: Boolean to use Redis. (default true)
1839 :arg redis: Redis config params
1840
1841 :Parameter: * **host** (`str`) Redis hostname\
1842 (default 'localhost')
1843 :Parameter: * **port** (`int`) Redis port number (default 6397)
1844 :Parameter: * **database-number** (`int`)\
1845 Redis database number (default 0)
1846 :Parameter: * **database-password** (`str`)\
1847 Redis database password (default '')
1848 :Parameter: * **data-type** (`str`)\
1849 Redis database type (default 'list')
1850 :Parameter: * **key** (`str`) Redis key (default 'logstash')
1851
1852 Example:
1853
1854 .. literalinclude:: /../../tests/wrappers/fixtures/logstash001.yaml
1855
1856 """
1857 logstash = XML.SubElement(
1858 xml_parent, "jenkins.plugins.logstash." "LogstashBuildWrapper"
1859 )
1860 logstash.set("plugin", "[email protected]")
1861
1862 mapping = [("use-redis", "useRedis", True)]
1863 helpers.convert_mapping_to_xml(logstash, data, mapping, fail_required=True)
1864
1865 if data.get("use-redis"):
1866 redis_config = data.get("redis", {})
1867 redis_sub_element = XML.SubElement(logstash, "redis")
1868
1869 mapping = [
1870 ("host", "host", "localhost"),
1871 ("port", "port", "6379"),
1872 ("database-number", "numb", "0"),
1873 ("database-password", "pass", ""),
1874 ("data-type", "dataType", "list"),
1875 ("key", "key", "logstash"),
1876 ]
1877 helpers.convert_mapping_to_xml(
1878 redis_sub_element, redis_config, mapping, fail_required=True
1879 )
1880
1881
1882 def mongo_db(registry, xml_parent, data):
1883 """yaml: mongo-db build wrapper
1884 Initializes a MongoDB database while running the build.
1885
1886 Requires the Jenkins :jenkins-plugins:`MongoDB plugin <mongodb>`.
1887
1888 :arg str name: The name of the MongoDB install to use (required)
1889 :arg str data-directory: Data directory for the server (default '')
1890 :arg int port: Port for the server (default '')
1891 :arg str startup-params: Startup parameters for the server (default '')
1892 :arg int start-timeout: How long to wait for the server to start in
1893 milliseconds. 0 means no timeout. (default 0)
1894
1895 Full Example:
1896
1897 .. literalinclude:: /../../tests/wrappers/fixtures/mongo-db-full.yaml
1898
1899 Minimal Example:
1900
1901 .. literalinclude:: /../../tests/wrappers/fixtures/mongo-db-minimal.yaml
1902 """
1903 mongodb = XML.SubElement(
1904 xml_parent, "org.jenkinsci.plugins.mongodb." "MongoBuildWrapper"
1905 )
1906 mongodb.set("plugin", "mongodb")
1907
1908 mapping = [
1909 ("name", "mongodbName", None),
1910 ("port", "port", ""),
1911 ("data-directory", "dbpath", ""),
1912 ("startup-params", "parameters", ""),
1913 ("start-timeout", "startTimeout", 0),
1914 ]
1915 helpers.convert_mapping_to_xml(mongodb, data, mapping, fail_required=True)
1916
1917
1918 def delivery_pipeline(registry, xml_parent, data):
1919 """yaml: delivery-pipeline
1920 If enabled the job will create a version based on the template.
1921 The version will be set to the environment variable PIPELINE_VERSION and
1922 will also be set in the downstream jobs.
1923
1924 Requires the Jenkins :jenkins-plugins:`Delivery Pipeline Plugin
1925 <delivery-pipeline-plugin>`.
1926
1927 :arg str version-template: Template for generated version e.g
1928 1.0.${BUILD_NUMBER} (default '')
1929 :arg bool set-display-name: Set the generated version as the display name
1930 for the build (default false)
1931
1932 Minimal Example:
1933
1934 .. literalinclude::
1935 /../../tests/wrappers/fixtures/delivery-pipeline-minimal.yaml
1936 :language: yaml
1937
1938 Full Example:
1939
1940 .. literalinclude::
1941 /../../tests/wrappers/fixtures/delivery-pipeline-full.yaml
1942 :language: yaml
1943 """
1944 pvc = XML.SubElement(
1945 xml_parent, "se.diabol.jenkins.pipeline.PipelineVersionContributor"
1946 )
1947 pvc.set("plugin", "delivery-pipeline-plugin")
1948
1949 mapping = [
1950 ("version-template", "versionTemplate", ""),
1951 ("set-display-name", "updateDisplayName", False),
1952 ]
1953 helpers.convert_mapping_to_xml(pvc, data, mapping, fail_required=True)
1954
1955
1956 def matrix_tie_parent(registry, xml_parent, data):
1957 """yaml: matrix-tie-parent
1958 Tie parent to a node.
1959
1960 Requires the Jenkins :jenkins-plugins:`Matrix Tie Parent Plugin
1961 <matrixtieparent>`.
1962
1963 Note that from Jenkins version 1.532 this plugin's functionality is
1964 available under the "advanced" option of the matrix project configuration.
1965 You can use the top level ``node`` parameter to control where the parent
1966 job is tied in Jenkins 1.532 and higher.
1967
1968 :arg str node: Name of the node (required)
1969
1970 Example:
1971
1972 .. literalinclude:: /../../tests/wrappers/fixtures/matrix-tie-parent.yaml
1973 """
1974 mtp = XML.SubElement(xml_parent, "matrixtieparent.BuildWrapperMtp")
1975 mapping = [("node", "labelName", None)]
1976 helpers.convert_mapping_to_xml(mtp, data, mapping, fail_required=True)
1977
1978
1979 def exclusion(registry, xml_parent, data):
1980 """yaml: exclusion
1981 Add a resource to use for critical sections to establish a mutex on. If
1982 another job specifies the same resource, the second job will wait for the
1983 blocked resource to become available.
1984
1985 Requires the Jenkins :jenkins-plugins:`Exclusion Plugin <Exclusion>`.
1986
1987 :arg list resources: List of resources to add for exclusion
1988
1989 Example:
1990
1991 .. literalinclude:: /../../tests/wrappers/fixtures/exclusion002.yaml
1992
1993 """
1994 exl = XML.SubElement(xml_parent, "org.jvnet.hudson.plugins.exclusion.IdAllocator")
1995 exl.set("plugin", "Exclusion")
1996 ids = XML.SubElement(exl, "ids")
1997 resources = data.get("resources", [])
1998 for resource in resources:
1999 dit = XML.SubElement(ids, "org.jvnet.hudson.plugins.exclusion.DefaultIdType")
2000 mapping = [("", "name", resource.upper())]
2001 helpers.convert_mapping_to_xml(dit, data, mapping, fail_required=True)
2002
2003
2004 def ssh_agent_credentials(registry, xml_parent, data):
2005 """yaml: ssh-agent-credentials
2006 Sets up the user for the ssh agent plugin for jenkins.
2007
2008 Requires the Jenkins :jenkins-plugins:`SSH-Agent Plugin <ssh-agent>`.
2009
2010 :arg list users: A list of Jenkins users credential IDs (required)
2011 :arg str user: The user id of the jenkins user credentials (deprecated)
2012 :arg bool ignore-missing-credentials: Specifies the option to ignore
2013 missing credentials (default false)
2014
2015 Example:
2016
2017 .. literalinclude::
2018 /../../tests/wrappers/fixtures/ssh-agent-credentials002.yaml
2019
2020
2021 if both **users** and **user** parameters specified, **users** will be
2022 preferred, **user** will be ignored.
2023
2024 Example:
2025
2026 .. literalinclude::
2027 /../../tests/wrappers/fixtures/ssh-agent-credentials003.yaml
2028
2029 Example:
2030
2031 .. literalinclude::
2032 /../../tests/wrappers/fixtures/ssh-agent-credentials004.yaml
2033
2034 equals to:
2035
2036 .. literalinclude::
2037 /../../tests/wrappers/fixtures/ssh-agent-credentials001.yaml
2038
2039 """
2040
2041 logger = logging.getLogger(__name__)
2042
2043 plugin_ver = registry.get_plugin_version("SSH Agent Plugin")
2044
2045 entry_xml = XML.SubElement(
2046 xml_parent, "com.cloudbees.jenkins.plugins.sshagent.SSHAgentBuildWrapper"
2047 )
2048 user_parent_entry_xml = entry_xml
2049 xml_key = "user"
2050
2051 user_list = list()
2052 if "users" in data:
2053 user_list += data["users"]
2054 if plugin_ver >= "1.5.0":
2055 user_parent_entry_xml = XML.SubElement(entry_xml, "credentialIds")
2056 xml_key = "string"
2057 if "user" in data:
2058 logger.warning(
2059 "Both 'users' and 'user' parameters specified for "
2060 "ssh-agent-credentials. 'users' is used, 'user' is "
2061 "ignored."
2062 )
2063 elif "user" in data:
2064 logger.warning(
2065 "The 'user' param has been deprecated, " "use the 'users' param instead."
2066 )
2067 user_list.append(data["user"])
2068 else:
2069 raise JenkinsJobsException(
2070 "Missing 'user' or 'users' parameter " "for ssh-agent-credentials"
2071 )
2072
2073 for user in user_list:
2074 XML.SubElement(user_parent_entry_xml, xml_key).text = user
2075
2076 mapping = [("ignore-missing-credentials", "ignoreMissing", False)]
2077 helpers.convert_mapping_to_xml(entry_xml, data, mapping, fail_required=False)
2078
2079
2080 def credentials_binding(registry, xml_parent, data):
2081 """yaml: credentials-binding
2082 Binds credentials to environment variables using the credentials binding
2083 plugin for jenkins.
2084
2085 Requires the Jenkins :jenkins-plugins:`Credentials Binding Plugin
2086 <credentials-binding>` version 1.1 or greater.
2087
2088 :arg list binding-type: List of each bindings to create. Bindings may be
2089 of type `zip-file`, `file`, `username-password`, `text`,
2090 `username-password-separated` or `amazon-web-services`.
2091 username-password sets a variable to the username and password given in
2092 the credentials, separated by a colon.
2093 username-password-separated sets one variable to the username and one
2094 variable to the password given in the credentials.
2095 amazon-web-services sets one variable to the access key and one
2096 variable to the secret access key. Requires the
2097 :jenkins-plugins:`AWS Credentials Plugin <aws-credentials>`
2098 .
2099
2100 :Parameters: * **credential-id** (`str`) UUID of the credential being
2101 referenced
2102 * **variable** (`str`) Environment variable where the
2103 credential will be stored
2104 * **username** (`str`) Environment variable for the
2105 username (Required for binding-type
2106 username-password-separated)
2107 * **password** (`str`) Environment variable for the
2108 password (Required for binding-type
2109 username-password-separated)
2110 * **access-key** (`str`) Environment variable for the
2111 access key (Required for binding-type
2112 amazon-web-services)
2113 * **secret-key** (`str`) Environment variable for the
2114 access secret key (Required for binding-type
2115 amazon-web-services)
2116 * **key-file-variable** (`str`) Environment variable
2117 to be set to the temporary path of the SSH key
2118 file during the build.
2119 * **username-variable** (`str`) Environment variable
2120 to be set to the username during
2121 the build. (optional)
2122 * **passphrase-variable** (`str`) Environment
2123 variable to be set to the password
2124 during the build. (optional)
2125 * **keystore-variable** (`str`) Environment
2126 variable to be set to the temporary
2127 keystore location during the build.
2128 * **password-variable** (`str`) Environment
2129 variable to be set to the password
2130 during the build.
2131 * **alias-variable** (`str`) Environment variable
2132 to be set to the keystore alias name
2133 of the certificate during the build.
2134
2135 Example:
2136
2137 .. literalinclude::
2138 /../../tests/wrappers/fixtures/credentials-binding-full.yaml
2139 :language: yaml
2140
2141 """
2142 entry_xml = xml_parent.find(
2143 "org.jenkinsci.plugins.credentialsbinding.impl.SecretBuildWrapper"
2144 )
2145 if entry_xml is None:
2146 entry_xml = XML.SubElement(
2147 xml_parent,
2148 "org.jenkinsci.plugins.credentialsbinding.impl.SecretBuildWrapper",
2149 )
2150
2151 bindings_xml = entry_xml.find("bindings")
2152 if bindings_xml is None:
2153 bindings_xml = XML.SubElement(entry_xml, "bindings")
2154
2155 binding_types = {
2156 "zip-file": "org.jenkinsci.plugins.credentialsbinding.impl." "ZipFileBinding",
2157 "file": "org.jenkinsci.plugins.credentialsbinding.impl.FileBinding",
2158 "username-password": "org.jenkinsci.plugins.credentialsbinding.impl."
2159 "UsernamePasswordBinding",
2160 "username-password-separated": "org.jenkinsci.plugins."
2161 "credentialsbinding.impl."
2162 "UsernamePasswordMultiBinding",
2163 "text": "org.jenkinsci.plugins.credentialsbinding.impl.StringBinding",
2164 "amazon-web-services": "com.cloudbees.jenkins.plugins.awscredentials"
2165 ".AmazonWebServicesCredentialsBinding",
2166 "ssh-user-private-key": "org.jenkinsci.plugins.credentialsbinding"
2167 ".impl.SSHUserPrivateKeyBinding",
2168 "docker-server-creds-binding": "org.jenkinsci.plugins.docker.commons"
2169 ".credentials.DockerServerCredentialsBinding",
2170 "cert-multi-binding": "org.jenkinsci.plugins.credentialsbinding"
2171 ".impl.CertificateMultiBinding",
2172 }
2173 for binding in data:
2174 for binding_type, params in binding.items():
2175 if binding_type not in binding_types.keys():
2176 raise JenkinsJobsException(
2177 "binding-type must be one of %r" % binding_types.keys()
2178 )
2179
2180 binding_xml = XML.SubElement(bindings_xml, binding_types[binding_type])
2181 if binding_type == "username-password-separated":
2182 mapping = [
2183 ("username", "usernameVariable", None),
2184 ("password", "passwordVariable", None),
2185 ]
2186 helpers.convert_mapping_to_xml(
2187 binding_xml, params, mapping, fail_required=True
2188 )
2189 elif binding_type == "amazon-web-services":
2190 mapping = [
2191 ("access-key", "accessKeyVariable", None),
2192 ("secret-key", "secretKeyVariable", None),
2193 ]
2194 helpers.convert_mapping_to_xml(
2195 binding_xml, params, mapping, fail_required=True
2196 )
2197 elif binding_type == "ssh-user-private-key":
2198 mapping = [("key-file-variable", "keyFileVariable", None)]
2199 if "username-variable" in params:
2200 mapping.append(("username-variable", "usernameVariable", None))
2201 if "passphrase-variable" in params:
2202 mapping.append(("passphrase-variable", "passphraseVariable", None))
2203 helpers.convert_mapping_to_xml(
2204 binding_xml, params, mapping, fail_required=True
2205 )
2206 elif binding_type == "cert-multi-binding":
2207 mapping = [
2208 ("keystore-variable", "keystoreVariable", None),
2209 ("password-variable", "passwordVariable", None),
2210 ("alias-variable", "aliasVariable", None),
2211 ]
2212 helpers.convert_mapping_to_xml(
2213 binding_xml, params, mapping, fail_required=True
2214 )
2215 else:
2216 mapping = [("variable", "variable", None)]
2217 helpers.convert_mapping_to_xml(
2218 binding_xml, params, mapping, fail_required=False
2219 )
2220 mapping = [("credential-id", "credentialsId", None)]
2221 helpers.convert_mapping_to_xml(
2222 binding_xml, params, mapping, fail_required=False
2223 )
2224
2225
2226 def custom_tools(registry, xml_parent, data):
2227 """yaml: custom-tools
2228 Requires the Jenkins :jenkins-plugins:`Custom Tools Plugin
2229 <custom-tools-plugin>`.
2230
2231 :arg list tools: List of custom tools to add
2232 (optional)
2233 :arg bool skip-master-install: skips the install in top level matrix job
2234 (default 'false')
2235 :arg bool convert-homes-to-upper: Converts the home env vars to uppercase
2236 (default 'false')
2237
2238 Example:
2239
2240 .. literalinclude:: /../../tests/wrappers/fixtures/custom-tools001.yaml
2241 """
2242 base = "com.cloudbees.jenkins.plugins.customtools"
2243 wrapper = XML.SubElement(xml_parent, base + ".CustomToolInstallWrapper")
2244
2245 wrapper_tools = XML.SubElement(wrapper, "selectedTools")
2246 tools = data.get("tools", [])
2247 tool_node = base + ".CustomToolInstallWrapper_-SelectedTool"
2248 for tool in tools:
2249 tool_wrapper = XML.SubElement(wrapper_tools, tool_node)
2250 mapping = [("", "name", tool)]
2251 helpers.convert_mapping_to_xml(tool_wrapper, data, mapping, fail_required=True)
2252
2253 opts = XML.SubElement(wrapper, "multiconfigOptions")
2254 mapping = [("skip-master-install", "skipMasterInstallation", False)]
2255 helpers.convert_mapping_to_xml(opts, data, mapping, fail_required=True)
2256
2257 mapping = [("convert-homes-to-upper", "convertHomesToUppercase", False)]
2258 helpers.convert_mapping_to_xml(wrapper, data, mapping, fail_required=True)
2259
2260
2261 def nodejs_installator(registry, xml_parent, data):
2262 """yaml: nodejs-installator
2263 Provides Jenkins integration for NodeJS & npm packages.
2264
2265 Requires the Jenkins :jenkins-plugins:`NodeJS Plugin
2266 <nodejs>`.
2267
2268 :arg str name: nodejs installation name (required)
2269
2270 Example:
2271
2272 .. literalinclude::
2273 /../../tests/wrappers/fixtures/nodejs-installator001.yaml
2274 """
2275 npm_node = XML.SubElement(
2276 xml_parent, "jenkins.plugins.nodejs." "NodeJSBuildWrapper"
2277 )
2278
2279 plugin_ver = registry.get_plugin_version("nodejs", default="0")
2280 npm_node.set("plugin", "nodejs@" + plugin_ver)
2281 mapping = [("name", "nodeJSInstallationName", None)]
2282 helpers.convert_mapping_to_xml(npm_node, data, mapping, fail_required=True)
2283
2284
2285 def xvnc(registry, xml_parent, data):
2286 """yaml: xvnc
2287 Enable xvnc during the build.
2288
2289 Requires the Jenkins :jenkins-plugins:`xvnc plugin <xvnc>`.
2290
2291 :arg bool screenshot: Take screenshot upon build completion (default false)
2292 :arg bool xauthority: Create a dedicated Xauthority file per build (default
2293 true)
2294
2295 Full Example:
2296
2297 .. literalinclude:: /../../tests/wrappers/fixtures/xvnc-full.yaml
2298 :language: yaml
2299
2300 Minimal Example:
2301
2302 .. literalinclude:: /../../tests/wrappers/fixtures/xvnc-minimal.yaml
2303 :language: yaml
2304 """
2305 xwrapper = XML.SubElement(xml_parent, "hudson.plugins.xvnc.Xvnc")
2306 xwrapper.set("plugin", "xvnc")
2307
2308 mapping = [
2309 ("screenshot", "takeScreenshot", False),
2310 ("xauthority", "useXauthority", True),
2311 ]
2312 helpers.convert_mapping_to_xml(xwrapper, data, mapping, fail_required=True)
2313
2314
2315 def job_log_logger(registry, xml_parent, data):
2316 """yaml: job-log-logger
2317 Enable writing the job log to the underlying logging system.
2318
2319 Requires the Jenkins :jenkins-plugins:`Job Log Logger plugin
2320 <job-log-logger-plugin>`.
2321
2322 :arg bool suppress-empty: Suppress empty log messages (default true)
2323
2324 Example:
2325
2326 .. literalinclude:: /../../tests/wrappers/fixtures/job-log-logger001.yaml
2327
2328 """
2329 top = XML.SubElement(
2330 xml_parent, "org.jenkins.ci.plugins.jobloglogger." "JobLogLoggerBuildWrapper"
2331 )
2332 mapping = [("suppress-empty", "suppressEmpty", True)]
2333 helpers.convert_mapping_to_xml(top, data, mapping, fail_required=True)
2334
2335
2336 def xvfb(registry, xml_parent, data):
2337 """yaml: xvfb
2338 Enable xvfb during the build.
2339
2340 Requires the Jenkins :jenkins-plugins:`Xvfb Plugin <xvfb>`.
2341
2342 :arg str installation-name: The name of the Xvfb tool installation (default
2343 'default')
2344 :arg bool auto-display-name: Uses the -displayfd option of Xvfb by which it
2345 chooses it's own display name (default false)
2346 :arg str display-name: Ordinal of the display Xvfb will be running on, if
2347 left empty chosen based on current build executor number (default '')
2348 :arg str assigned-labels: If you want to start Xvfb only on specific nodes
2349 specify its name or label (default '')
2350 :arg bool parallel-build: When running multiple Jenkins nodes on the same
2351 machine this setting influences the display number generation (default
2352 false)
2353 :arg int timeout: A timeout of given seconds to wait before returning
2354 control to the job (default 0)
2355 :arg str screen: Resolution and color depth. (default '1024x768x24')
2356 :arg int display-name-offset: Offset for display names. (default 1)
2357 :arg str additional-options: Additional options to be added with the
2358 options above to the Xvfb command line (default '')
2359 :arg bool debug: If Xvfb output should appear in console log of this job
2360 (default false)
2361 :arg bool shutdown-with-build: Should the display be kept until the whole
2362 job ends (default false)
2363
2364 Full Example:
2365
2366 .. literalinclude:: /../../tests/wrappers/fixtures/xvfb-full.yaml
2367 :language: yaml
2368
2369 Minimal Example:
2370
2371 .. literalinclude:: /../../tests/wrappers/fixtures/xvfb-minimal.yaml
2372 :language: yaml
2373 """
2374 xwrapper = XML.SubElement(xml_parent, "org.jenkinsci.plugins.xvfb.XvfbBuildWrapper")
2375
2376 mapping = [
2377 ("installation-name", "installationName", "default"),
2378 ("auto-display-name", "autoDisplayName", False),
2379 ("display-name", "displayName", ""),
2380 ("assigned-labels", "assignedLabels", ""),
2381 ("parallel-build", "parallelBuild", False),
2382 ("timeout", "timeout", 0),
2383 ("screen", "screen", "1024x768x24"),
2384 ("display-name-offset", "displayNameOffset", 1),
2385 ("additional-options", "additionalOptions", ""),
2386 ("debug", "debug", False),
2387 ("shutdown-with-build", "shutdownWithBuild", False),
2388 ]
2389 helpers.convert_mapping_to_xml(xwrapper, data, mapping, fail_required=True)
2390
2391
2392 def android_emulator(registry, xml_parent, data):
2393 """yaml: android-emulator
2394 Automates many Android development tasks including SDK installation,
2395 build file generation, emulator creation and launch,
2396 APK (un)installation...
2397
2398 Requires the Jenkins :jenkins-plugins:`Android Emulator Plugin
2399 <android-emulator>`.
2400
2401 :arg str avd: Enter the name of an existing Android emulator configuration.
2402 If this is exclusive with the 'os' arg.
2403 :arg str os: Can be an OS version, target name or SDK add-on
2404 :arg str screen-density: Density in dots-per-inch (dpi) or as an alias,
2405 e.g. "160" or "mdpi". (default mdpi)
2406 :arg str screen-resolution: Can be either a named resolution or explicit
2407 size, e.g. "WVGA" or "480x800". (default WVGA)
2408 :arg str locale: Language and country pair. (default en_US)
2409 :arg str target-abi: Name of the ABI / system image to be used. (optional)
2410 :arg str sd-card: sd-card size e.g. "32M" or "10240K". (optional)
2411 :arg bool wipe: if true, the emulator will have its user data reset at
2412 start-up (default false)
2413 :arg bool show-window: if true, the Android emulator user interface will
2414 be displayed on screen during the build. (default false)
2415 :arg bool snapshot: Start emulator from stored state (default false)
2416 :arg bool delete: Delete Android emulator at the end of build
2417 (default false)
2418 :arg int startup-delay: Wait this many seconds before attempting
2419 to start the emulator (default 0)
2420 :arg str commandline-options: Will be given when starting the
2421 Android emulator executable (optional)
2422 :arg str exe: The emulator executable. (optional)
2423 :arg list hardware-properties: Dictionary of hardware properties. Allows
2424 you to override the default values for an AVD. (optional)
2425
2426 Example:
2427
2428 .. literalinclude:: /../../tests/wrappers/fixtures/android003.yaml
2429 """
2430 root = XML.SubElement(
2431 xml_parent, "hudson.plugins.android__emulator.AndroidEmulator"
2432 )
2433
2434 if data.get("avd") and data.get("os"):
2435 raise JenkinsJobsException(
2436 "'avd' and 'os' options are " "exclusive, please pick one only"
2437 )
2438
2439 if not data.get("avd") and not data.get("os"):
2440 raise JenkinsJobsException(
2441 "AndroidEmulator requires an AVD name or"
2442 "OS version to run: specify 'os' or 'avd'"
2443 )
2444
2445 if data.get("avd"):
2446 XML.SubElement(root, "avdName").text = str(data["avd"])
2447
2448 else:
2449 mapping = [
2450 ("os", "osVersion", None),
2451 ("screen-density", "screenDensity", "mdpi"),
2452 ("screen-resolution", "screenResolution", "WVGA"),
2453 ("locale", "deviceLocale", "en_US"),
2454 ("target-abi", "targetAbi", ""),
2455 ("sd-card", "sdCardSize", ""),
2456 ]
2457 helpers.convert_mapping_to_xml(root, data, mapping, fail_required=True)
2458
2459 hardware = XML.SubElement(root, "hardwareProperties")
2460 for prop_name, prop_val in data.get("hardware-properties", {}).items():
2461 prop_node = XML.SubElement(
2462 hardware,
2463 "hudson.plugins.android__emulator" ".AndroidEmulator_-HardwareProperty",
2464 )
2465 mapping = [("", "key", prop_name), ("", "value", prop_val)]
2466 helpers.convert_mapping_to_xml(prop_node, data, mapping, fail_required=True)
2467 mapping = [
2468 ("wipe", "wipeData", False),
2469 ("show-window", "showWindow", False),
2470 ("snapshot", "useSnapshots", False),
2471 ("delete", "deleteAfterBuild", False),
2472 ("startup-delay", "startupDelay", 0),
2473 ("commandline-options", "commandLineOptions", ""),
2474 ("exe", "executable", ""),
2475 ]
2476 helpers.convert_mapping_to_xml(root, data, mapping, fail_required=True)
2477
2478
2479 def artifactory_maven(registry, xml_parent, data):
2480 """yaml: artifactory-maven
2481 Wrapper for non-Maven projects.
2482
2483 Requires the Jenkins :jenkins-plugins:`Artifactory Plugin <artifactory>`
2484
2485 :arg str url: URL of the Artifactory server. e.g.
2486 https://jfrog.com/artifactory/ (default '')
2487 :arg str name: Artifactory user with permissions use for
2488 connected to the selected Artifactory Server
2489 (default '')
2490 :arg str repo-key: Name of the repository to search for
2491 artifact dependencies. Provide a single repo-key or provide
2492 separate release-repo-key and snapshot-repo-key.
2493 :arg str release-repo-key: Release repository name. Value of
2494 repo-key take priority over release-repo-key if provided.
2495 :arg str snapshot-repo-key: Snapshots repository name. Value of
2496 repo-key take priority over release-repo-key if provided.
2497
2498 Example:
2499
2500 .. literalinclude:: /../../tests/wrappers/fixtures/artifactory001.yaml
2501 :language: yaml
2502
2503 """
2504
2505 artifactory = XML.SubElement(
2506 xml_parent, "org.jfrog.hudson.maven3.ArtifactoryMaven3NativeConfigurator"
2507 )
2508
2509 # details
2510 details = XML.SubElement(artifactory, "details")
2511 helpers.artifactory_common_details(details, data)
2512
2513 if "repo-key" in data:
2514 mapping = [("repo-key", "downloadRepositoryKey", None)]
2515 else:
2516 mapping = [
2517 ("snapshot-repo-key", "downloadSnapshotRepositoryKey", ""),
2518 ("release-repo-key", "downloadReleaseRepositoryKey", ""),
2519 ]
2520 helpers.convert_mapping_to_xml(details, data, mapping, fail_required=True)
2521
2522
2523 def artifactory_generic(registry, xml_parent, data):
2524 """yaml: artifactory-generic
2525 Wrapper for non-Maven projects.
2526
2527 Requires the Jenkins :jenkins-plugins:`Artifactory Plugin <artifactory>`
2528
2529 :arg str url: URL of the Artifactory server. e.g.
2530 https://jfrog.com/artifactory/ (default '')
2531 :arg str name: Artifactory user with permissions use for
2532 connected to the selected Artifactory Server
2533 (default '')
2534 :arg str repo-key: Release repository name (plugin < 2.3.0) (default '')
2535 :arg str snapshot-repo-key: Snapshots repository name (plugin < 2.3.0)
2536 (default '')
2537 :arg str key-from-select: Repository key to use (plugin >= 2.3.0)
2538 (default '')
2539 :arg str key-from-text: Repository key to use that can be configured
2540 dynamically using Jenkins variables (plugin >= 2.3.0) (default '')
2541 :arg str upload-spec: File Spec schema for uploading files is as follows
2542 (default '')
2543 :arg str download-spec: File Spec schema for downloading
2544 files is as follows (default '')
2545 :arg str upload-spec-file: File location for uploading Spec schema
2546 (default '')
2547 :arg str download-spec-file: File location for downloading Spec schema
2548 (default '')
2549 :arg list deploy-pattern: List of patterns for mappings
2550 build artifacts to published artifacts. Supports Ant-style wildcards
2551 mapping to target directories. E.g.: */*.zip=>dir (default [])
2552 :arg list resolve-pattern: List of references to other
2553 artifacts that this build should use as dependencies.
2554 :arg list matrix-params: List of properties to attach to all deployed
2555 artifacts in addition to the default ones: build.name, build.number,
2556 and vcs.revision (default [])
2557 :arg bool deploy-build-info: Deploy jenkins build metadata with
2558 artifacts to Artifactory (default false)
2559 :arg bool env-vars-include: Include environment variables accessible by
2560 the build process. Jenkins-specific env variables are always included.
2561 Use the env-vars-include-patterns and env-vars-exclude-patterns to
2562 filter the environment variables published to artifactory.
2563 (default false)
2564 :arg list env-vars-include-patterns: List of environment variable patterns
2565 for including env vars as part of the published build info. Environment
2566 variables may contain the * and the ? wildcards (default [])
2567 :arg list env-vars-exclude-patterns: List of environment variable patterns
2568 that determine the env vars excluded from the published build info
2569 (default [])
2570 :arg bool discard-old-builds:
2571 Remove older build info from Artifactory (default false)
2572 :arg bool discard-build-artifacts:
2573 Remove older build artifacts from Artifactory (default false)
2574
2575 Example:
2576
2577 .. literalinclude:: /../../tests/wrappers/fixtures/artifactory002.yaml
2578 :language: yaml
2579
2580 """
2581
2582 use_specs = False
2583 artifactory = XML.SubElement(
2584 xml_parent, "org.jfrog.hudson.generic.ArtifactoryGenericConfigurator"
2585 )
2586
2587 # details
2588 details = XML.SubElement(artifactory, "details")
2589 helpers.artifactory_common_details(details, data)
2590
2591 # Get plugin information to maintain backwards compatibility
2592 plugin_ver = registry.get_plugin_version("artifactory")
2593
2594 if plugin_ver >= "2.3.0":
2595 deploy_release_repo = XML.SubElement(details, "deployReleaseRepository")
2596 mapping = [
2597 ("key-from-text", "keyFromText", ""),
2598 ("key-from-select", "keyFromSelect", ""),
2599 ("key-from-text", "dynamicMode", ""),
2600 ]
2601 helpers.convert_mapping_to_xml(
2602 deploy_release_repo, data, mapping, fail_required=False
2603 )
2604 else:
2605 mapping = [
2606 ("repo-key", "repositoryKey", ""),
2607 ("snapshot-repo-key", "snapshotsRepositoryKey", ""),
2608 ]
2609 helpers.convert_mapping_to_xml(details, data, mapping, fail_required=False)
2610
2611 if "upload-spec" in data or "download-spec" in data:
2612 upload_spec = data.get("upload-spec", "")
2613 upl_spec_xml = XML.SubElement(artifactory, "uploadSpec")
2614 XML.SubElement(upl_spec_xml, "spec").text = upload_spec
2615
2616 download_spec = data.get("download-spec", "")
2617 dnl_spec_xml = XML.SubElement(artifactory, "downloadSpec")
2618 XML.SubElement(dnl_spec_xml, "spec").text = download_spec
2619 use_specs = True
2620
2621 if "upload-spec-file" in data or "download-spec-file" in data:
2622 upload_spec_file = data.get("upload-spec-file", "")
2623 upl_spec_xml = XML.SubElement(artifactory, "uploadSpec")
2624 XML.SubElement(upl_spec_xml, "filePath").text = upload_spec_file
2625
2626 download_spec_file = data.get("download-spec-file", "")
2627 dnl_spec_xml = XML.SubElement(artifactory, "downloadSpec")
2628 XML.SubElement(dnl_spec_xml, "filePath").text = download_spec_file
2629 use_specs = True
2630
2631 XML.SubElement(artifactory, "useSpecs").text = str(use_specs).lower()
2632
2633 XML.SubElement(artifactory, "deployPattern").text = ",".join(
2634 data.get("deploy-pattern", [])
2635 )
2636 XML.SubElement(artifactory, "resolvePattern").text = ",".join(
2637 data.get("resolve-pattern", [])
2638 )
2639 XML.SubElement(artifactory, "matrixParams").text = ",".join(
2640 data.get("matrix-params", [])
2641 )
2642 mapping = [
2643 ("deploy-build-info", "deployBuildInfo", False),
2644 ("env-vars-include", "includeEnvVars", False),
2645 ("discard-old-builds", "discardOldBuilds", False),
2646 ("discard-build-artifacts", "discardBuildArtifacts", True),
2647 ]
2648 helpers.convert_mapping_to_xml(artifactory, data, mapping, fail_required=False)
2649
2650 # envVarsPatterns
2651 helpers.artifactory_env_vars_patterns(artifactory, data)
2652
2653
2654 def artifactory_maven_freestyle(registry, xml_parent, data):
2655 """yaml: artifactory-maven-freestyle
2656 Wrapper for Free Stype projects.
2657
2658 Requires the Jenkins :jenkins-plugins:`Artifactory Plugin <artifactory>`
2659
2660 :arg str url: URL of the Artifactory server. e.g.
2661 https://jfrog.com/artifactory/ (default '')
2662 :arg str name: Artifactory user with permissions use for
2663 connected to the selected Artifactory Server (default '')
2664 :arg str release-repo-key: Release repository name (default '')
2665 :arg str snapshot-repo-key: Snapshots repository name (default '')
2666 :arg bool publish-build-info: Push build metadata with artifacts
2667 (default false)
2668 :arg bool discard-old-builds:
2669 Remove older build info from Artifactory (default true)
2670 :arg bool discard-build-artifacts:
2671 Remove older build artifacts from Artifactory (default false)
2672 :arg bool include-env-vars: Include all environment variables
2673 accessible by the build process. Jenkins-specific env variables
2674 are always included (default false)
2675 :arg bool run-checks: Run automatic license scanning check after the
2676 build is complete (default false)
2677 :arg bool include-publish-artifacts: Include the build's published
2678 module artifacts in the license violation checks if they are
2679 also used as dependencies for other modules in this build
2680 (default false)
2681 :arg bool license-auto-discovery: Tells Artifactory not to try
2682 and automatically analyze and tag the build's dependencies
2683 with license information upon deployment (default true)
2684 :arg bool enable-issue-tracker-integration: When the Jenkins
2685 JIRA plugin is enabled, synchronize information about JIRA
2686 issues to Artifactory and attach issue information to build
2687 artifacts (default false)
2688 :arg bool aggregate-build-issues: When the Jenkins JIRA plugin
2689 is enabled, include all issues from previous builds up to the
2690 latest build status defined in "Aggregation Build Status"
2691 (default false)
2692 :arg bool filter-excluded-artifacts-from-build: Add the excluded
2693 files to the excludedArtifacts list and remove them from the
2694 artifacts list in the build info (default false)
2695 :arg str scopes: A list of dependency scopes/configurations to run
2696 license violation checks on. If left empty all dependencies from
2697 all scopes will be checked (default '')
2698 :arg str violation-recipients: Recipients that need to be notified
2699 of license violations in the build info (default '')
2700 :arg list matrix-params: List of properties to attach to all
2701 deployed artifacts in addition to the default ones:
2702 build.name, build.number, and vcs.revision (default '')
2703 :arg str black-duck-app-name: The existing Black Duck Code Center
2704 application name (default '')
2705 :arg str black-duck-app-version: The existing Black Duck Code Center
2706 application version (default '')
2707 :arg str black-duck-report-recipients: Recipients that will be emailed
2708 a report after the automatic Black Duck Code Center compliance checks
2709 finished (default '')
2710 :arg str black-duck-scopes: A list of dependency scopes/configurations
2711 to run Black Duck Code Center compliance checks on. If left empty
2712 all dependencies from all scopes will be checked (default '')
2713 :arg bool black-duck-run-checks: Automatic Black Duck Code Center
2714 compliance checks will occur after the build completes
2715 (default false)
2716 :arg bool black-duck-include-published-artifacts: Include the build's
2717 published module artifacts in the license violation checks if they
2718 are also used as dependencies for other modules in this build
2719 (default false)
2720 :arg bool auto-create-missing-component-requests: Auto create
2721 missing components in Black Duck Code Center application after
2722 the build is completed and deployed in Artifactory
2723 (default true)
2724 :arg bool auto-discard-stale-component-requests: Auto discard
2725 stale components in Black Duck Code Center application after
2726 the build is completed and deployed in Artifactory
2727 (default true)
2728 :arg bool deploy-artifacts: Push artifacts to the Artifactory
2729 Server. The specific artifacts to push are controlled using
2730 the deployment-include-patterns and deployment-exclude-patterns.
2731 (default true)
2732 :arg list deployment-include-patterns: List of patterns for including
2733 build artifacts to publish to artifactory. (default[]')
2734 :arg list deployment-exclude-patterns: List of patterns
2735 for excluding artifacts from deployment to Artifactory
2736 (default [])
2737 :arg bool env-vars-include: Include environment variables
2738 accessible by the build process. Jenkins-specific env variables
2739 are always included. Environment variables can be filtered using
2740 the env-vars-include-patterns nad env-vars-exclude-patterns.
2741 (default false)
2742 :arg list env-vars-include-patterns: List of environment variable patterns
2743 that will be included as part of the published build info. Environment
2744 variables may contain the * and the ? wildcards (default [])
2745 :arg list env-vars-exclude-patterns: List of environment variable patterns
2746 that will be excluded from the published build info
2747 (default [])
2748
2749 Example:
2750
2751 .. literalinclude:: /../../tests/wrappers/fixtures/artifactory003.yaml
2752 :language: yaml
2753
2754 """
2755
2756 artifactory = XML.SubElement(
2757 xml_parent, "org.jfrog.hudson.maven3.ArtifactoryMaven3Configurator"
2758 )
2759
2760 # details
2761 details = XML.SubElement(artifactory, "details")
2762 helpers.artifactory_common_details(details, data)
2763
2764 deploy_release = XML.SubElement(details, "deployReleaseRepository")
2765 helpers.artifactory_repository(deploy_release, data, "release")
2766
2767 deploy_snapshot = XML.SubElement(details, "deploySnapshotRepository")
2768 helpers.artifactory_repository(deploy_snapshot, data, "snapshot")
2769
2770 XML.SubElement(details, "stagingPlugin").text = data.get(
2771 "resolve-staging-plugin", ""
2772 )
2773
2774 # resolverDetails
2775 resolver = XML.SubElement(artifactory, "resolverDetails")
2776 helpers.artifactory_common_details(resolver, data)
2777
2778 resolve_snapshot = XML.SubElement(resolver, "resolveSnapshotRepository")
2779 helpers.artifactory_repository(resolve_snapshot, data, "snapshot")
2780
2781 deploy_release = XML.SubElement(resolver, "resolveReleaseRepository")
2782 helpers.artifactory_repository(deploy_release, data, "release")
2783
2784 XML.SubElement(resolver, "stagingPlugin").text = data.get(
2785 "resolve-staging-plugin", ""
2786 )
2787
2788 # artifactDeploymentPatterns
2789 helpers.artifactory_deployment_patterns(artifactory, data)
2790
2791 # envVarsPatterns
2792 helpers.artifactory_env_vars_patterns(artifactory, data)
2793
2794 XML.SubElement(artifactory, "matrixParams").text = ",".join(
2795 data.get("matrix-params", [])
2796 )
2797
2798 # optional__props
2799 helpers.artifactory_optional_props(artifactory, data, "wrappers")
2800
2801
2802 def maven_release(registry, xml_parent, data):
2803 """yaml: maven-release
2804 Wrapper for Maven projects
2805
2806 Requires the Jenkins :jenkins-plugins:`M2 Release Plugin <m2release>`
2807
2808 :arg str release-goals: Release goals and options (default '')
2809 :arg str dry-run-goals: DryRun goals and options (default '')
2810 :arg int num-successful-builds: Number of successful release builds to keep
2811 (default 1)
2812 :arg bool select-custom-scm-comment-prefix: Preselect 'Specify custom SCM
2813 comment prefix' (default false)
2814 :arg bool select-append-jenkins-username: Preselect 'Append Jenkins
2815 Username' (default false)
2816 :arg bool select-scm-credentials: Preselect 'Specify SCM login/password'
2817 (default false)
2818 :arg str release-env-var: Release environment variable (default '')
2819 :arg str scm-user-env-var: SCM username environment variable (default '')
2820 :arg str scm-password-env-var: SCM password environment variable
2821 (default '')
2822
2823 Example:
2824
2825 .. literalinclude:: /../../tests/wrappers/fixtures/maven-release001.yaml
2826 :language: yaml
2827
2828 """
2829 mvn_release = XML.SubElement(
2830 xml_parent, "org.jvnet.hudson.plugins.m2release." "M2ReleaseBuildWrapper"
2831 )
2832
2833 mapping = [
2834 ("release-goals", "releaseGoals", ""),
2835 ("dry-run-goals", "dryRunGoals", ""),
2836 ("num-successful-builds", "numberOfReleaseBuildsToKeep", 1),
2837 ("select-custom-scm-comment-prefix", "selectCustomScmCommentPrefix", False),
2838 ("select-append-jenkins-username", "selectAppendHudsonUsername", False),
2839 ("select-scm-credentials", "selectScmCredentials", False),
2840 ("release-env-var", "releaseEnvVar", ""),
2841 ("scm-user-env-var", "scmUserEnvVar", ""),
2842 ("scm-password-env-var", "scmPasswordEnvVar", ""),
2843 ]
2844 helpers.convert_mapping_to_xml(mvn_release, data, mapping, fail_required=True)
2845
2846
2847 def version_number(parser, xml_parent, data):
2848 """yaml: version-number
2849 Generate a version number for the build using a format string. See the
2850 wiki page for more detailed descriptions of options.
2851
2852 Requires the Jenkins :jenkins-plugins:`Version number plugin
2853 <versionnumber>`.
2854
2855 :arg str variable-name: Name of environment variable to assign version
2856 number to (required)
2857 :arg str format-string: Format string used to generate version number
2858 (required)
2859 :arg str prefix-variable: Variable that contains version number prefix
2860 (optional)
2861 :arg bool skip-failed-builds: If the build fails, DO NOT increment any
2862 auto-incrementing component of the version number (default: false)
2863 :arg bool display-name: Use the version number for the build display
2864 name (default: false)
2865 :arg str start-date: The date the project began as a UTC timestamp
2866 (default 1970-1-1 00:00:00.0 UTC)
2867 :arg int builds-today: The number of builds that have been executed
2868 today (optional)
2869 :arg int builds-this-month: The number of builds that have been executed
2870 since the start of the month (optional)
2871 :arg int builds-this-year: The number of builds that have been executed
2872 since the start of the year (optional)
2873 :arg int builds-all-time: The number of builds that have been executed
2874 since the start of the project (optional)
2875
2876 Example:
2877
2878 .. literalinclude:: /../../tests/wrappers/fixtures/version-number001.yaml
2879 :language: yaml
2880
2881 """
2882 version_number = XML.SubElement(
2883 xml_parent, "org.jvnet.hudson.tools.versionnumber.VersionNumberBuilder"
2884 )
2885
2886 mapping = [
2887 # option, xml name, default value
2888 ("variable-name", "environmentVariableName", None),
2889 ("format-string", "versionNumberString", None),
2890 ("prefix-variable", "environmentPrefixVariable", ""),
2891 ("skip-failed-builds", "skipFailedBuilds", False),
2892 ("display-name", "useAsBuildDisplayName", False),
2893 ("start-date", "projectStartDate", "1970-1-1 00:00:00.0 UTC"),
2894 ("builds-today", "oBuildsToday", "-1"),
2895 ("builds-this-month", "oBuildsThisMonth", "-1"),
2896 ("builds-this-year", "oBuildsThisYear", "-1"),
2897 ("builds-all-time", "oBuildsAllTime", "-1"),
2898 ]
2899
2900 helpers.convert_mapping_to_xml(version_number, data, mapping, fail_required=True)
2901
2902
2903 def github_pull_request(parser, xml_parent, data):
2904 """yaml: github-pull-request
2905 Set GitHub commit status with custom context and message.
2906
2907 Requires the Jenkins :jenkins-plugins:`GitHub Pull Request Builder Plugin
2908 <ghprb>`.
2909
2910 :arg bool show-matrix-status: Only post commit status of parent matrix job
2911 (default false)
2912 :arg str status-context: The context to include on PR status comments
2913 (default '')
2914 :arg str triggered-status: The status message to set when the build has
2915 been triggered (default '')
2916 :arg str started-status: The status message to set when the build has
2917 been started (default '')
2918 :arg str status-url: The status URL to set (default '')
2919 :arg bool status-add-test-results: Add test result one-liner to status
2920 message (default false)
2921 :arg list statuses: List of custom statuses on the commit for when a build
2922 is completed
2923
2924 :Status:
2925 * **message** (`str`) -- The message that is appended to a comment
2926 when a build finishes with the desired build status. If no status
2927 updates should be made when a build finishes with the indicated
2928 build status, use "--none--" to alert the trigger. (required)
2929 * **result** (`str`) -- Build result. Can be one of 'SUCCESS',
2930 'ERROR' or 'FAILURE'. (required)
2931
2932 Minimal Example:
2933
2934 .. literalinclude::
2935 /../../tests/wrappers/fixtures/github-pull-request-minimal.yaml
2936 :language: yaml
2937
2938 Full Example:
2939
2940 .. literalinclude::
2941 /../../tests/wrappers/fixtures/github-pull-request-full.yaml
2942 :language: yaml
2943
2944 """
2945 ghprb = XML.SubElement(
2946 xml_parent, "org.jenkinsci.plugins.ghprb.upstream.GhprbUpstreamStatus"
2947 )
2948
2949 mapping = [
2950 # option, xml name, default value
2951 ("show-matrix-status", "showMatrixStatus", False),
2952 ("status-context", "commitStatusContext", ""),
2953 ("triggered-status", "triggeredStatus", ""),
2954 ("started-status", "startedStatus", ""),
2955 ("status-url", "statusUrl", ""),
2956 ("status-add-test-results", "addTestResults", False),
2957 ]
2958 helpers.convert_mapping_to_xml(ghprb, data, mapping, fail_required=True)
2959
2960 statuses = data.get("statuses", [])
2961 if statuses:
2962 status_mapping = [("message", "message", None), ("result", "result", "")]
2963 result_list = ["ERROR", "SUCCESS", "FAILURE"]
2964
2965 completed_tag = XML.SubElement(ghprb, "completedStatus")
2966 for status in statuses:
2967 result = status.get("result", "")
2968 if result not in result_list:
2969 raise JenkinsJobsException(
2970 "'result' must be one of: " + ", ".join(result_list)
2971 )
2972
2973 result_tag = XML.SubElement(
2974 completed_tag,
2975 "org.jenkinsci.plugins.ghprb.extensions"
2976 ".comments.GhprbBuildResultMessage",
2977 )
2978 helpers.convert_mapping_to_xml(
2979 result_tag, status, status_mapping, fail_required=True
2980 )
2981
2982
2983 class Wrappers(jenkins_jobs.modules.base.Base):
2984 sequence = 80
2985
2986 component_type = "wrapper"
2987 component_list_type = "wrappers"
2988
2989 def gen_xml(self, xml_parent, data):
2990 if data.get("project-type", "freestyle") == "pipeline":
2991 logger.debug("Build wrappers skipped for Pipeline job")
2992 return
2993
2994 xml_wrappers = XML.SubElement(xml_parent, "buildWrappers")
2995
2996 self.dispatch_component_list("wrapper", data.get("wrappers", []), xml_wrappers)