Debian Codegraph @

jenkins_jobs/modules/publishers.py

raw
1 # Copyright 2012 Hewlett-Packard Development Company, L.P.
2 # Copyright 2012 Varnish Software AS
3 # Copyright 2013-2014 Antoine "hashar" Musso
4 # Copyright 2013-2014 Wikimedia Foundation Inc.
5 #
6 # Licensed under the Apache License, Version 2.0 (the "License");
7 # you may not use this file except in compliance with the License.
8 # You may obtain a copy of the License at
9 #
10 # http://www.apache.org/licenses/LICENSE-2.0
11 #
12 # Unless required by applicable law or agreed to in writing, software
13 # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
14 # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
15 # License for the specific language governing permissions and limitations
16 # under the License.
17
18
19 """
20 Publishers define actions that the Jenkins job should perform after
21 the build is complete.
22
23 **Component**: publishers
24 :Macro: publisher
25 :Entry Point: jenkins_jobs.publishers
26 """
27
28 import logging
29 import xml.etree.ElementTree as XML
30
31 import six
32
33 from jenkins_jobs.errors import InvalidAttributeError
34 from jenkins_jobs.errors import JenkinsJobsException
35 from jenkins_jobs.errors import MissingAttributeError
36 import jenkins_jobs.modules.base
37 from jenkins_jobs.modules import hudson_model
38 import jenkins_jobs.modules.helpers as helpers
39
40 logger = logging.getLogger(__name__)
41
42
43 def influx_db(registry, xml_parent, data):
44 """yaml: influx-db
45 Requires the Jenkins :jenkins-plugins: `Influx DB
46 <influxdb>`.
47 """
48
49 influx_db = XML.SubElement(
50 xml_parent,
51 "jenkinsci.plugins.influxdb.InfluxDbPublisher",
52 {"plugin": "influx-db"},
53 )
54
55 mapping = [
56 ("selected-target", "selectedTarget", ""),
57 ("custom-project-name", "customProjectName", ""),
58 ("custom-prefix", "customPrefix", ""),
59 ("jenkins-env-parameter-field", "jenkinsEnvParameterField", ""),
60 ("jenkins-env-parameter-tag", "jenkinsEnvParameterTag", ""),
61 ]
62
63 helpers.convert_mapping_to_xml(influx_db, data, mapping, fail_required=True)
64
65
66 def allure(registry, xml_parent, data):
67 """yaml: allure
68
69 Publish Allure report for the build. Requires the Jenkins
70 :jenkins-plugins:`Allure Plugin <allure-jenkins-plugin>`.
71
72 :arg str jdk: String identifier for a JDK installation in Jenkins
73 :arg str commandline: String identifier for a Allure-commandline tool
74 installation
75 :arg str report-build-policy: String identifier for a report build
76 policy enum. Possible values: 'ALWAYS', 'UNSTABLE', 'UNSUCCESSFUL'.
77 (By default is 'ALWAYS')
78 :arg bool include-properties: Flag to include specified properties
79 :arg list results-paths: List of results directories
80 :arg list properties: List of key:value property pairs
81
82 Minimal Example:
83
84 .. literalinclude::
85 /../../tests/publishers/fixtures/allure-minimal.yaml
86 :language: yaml
87
88 Full Example:
89
90 .. literalinclude:: /../../tests/publishers/fixtures/allure-full.yaml
91 :language: yaml
92
93 """
94 publisher_class = "ru.yandex.qatools.allure.jenkins.AllureReportPublisher"
95 property_class = "ru.yandex.qatools.allure.jenkins.config.PropertyConfig"
96 results_class = "ru.yandex.qatools.allure.jenkins.config.ResultsConfig"
97
98 allure_publisher = XML.SubElement(xml_parent, publisher_class)
99 allure_publisher.set("plugin", "allure-jenkins-plugin")
100 config = XML.SubElement(allure_publisher, "config")
101
102 results = XML.SubElement(config, "results")
103 if "results-paths" in data:
104 for results_path in data["results-paths"]:
105 entry = XML.SubElement(results, results_class)
106 path = XML.SubElement(entry, "path")
107 path.text = results_path["path"]
108
109 properties = XML.SubElement(config, "properties")
110 if "properties" in data:
111 property_mapping = [("key", "key", None), ("value", "value", None)]
112 for prop in data["properties"]:
113 entry = XML.SubElement(properties, property_class)
114 helpers.convert_mapping_to_xml(
115 entry, prop, property_mapping, fail_required=True
116 )
117 else:
118 properties.set("class", "empty-list")
119
120 mapping = [
121 ("jdk", "jdk", ""),
122 ("commandline", "commandline", ""),
123 (
124 "report-build-policy",
125 "reportBuildPolicy",
126 "ALWAYS",
127 ["ALWAYS", "UNSTABLE", "UNSUCCESSFUL"],
128 ),
129 ("include-properties", "includeProperties", False),
130 ]
131
132 helpers.convert_mapping_to_xml(config, data, mapping, fail_required=True)
133
134
135 def archive(registry, xml_parent, data):
136 """yaml: archive
137 Archive build artifacts
138
139 :arg str artifacts: path specifier for artifacts to archive
140 :arg str excludes: path specifier for artifacts to exclude (optional)
141 :arg bool latest-only: only keep the artifacts from the latest
142 successful build
143 :arg bool allow-empty: pass the build if no artifacts are
144 found (default false)
145 :arg bool follow-symlinks: follow symbolic links during archiving
146 (default false)
147 :arg bool only-if-success: archive artifacts only if build is successful
148 (default false)
149 :arg bool fingerprint: fingerprint all archived artifacts (default false)
150 :arg bool default-excludes: This option allows you to enable or disable the
151 default Ant exclusions. (default true)
152 :arg bool case-sensitive: Treat include and exclude patterns as case
153 sensitive. (default true)
154
155 Example:
156
157 .. literalinclude:: /../../tests/publishers/fixtures/archive001.yaml
158 :language: yaml
159 """
160 archiver = XML.SubElement(xml_parent, "hudson.tasks.ArtifactArchiver")
161 mapping = [
162 ("artifacts", "artifacts", None),
163 ("allow-empty", "allowEmptyArchive", False),
164 ("only-if-success", "onlyIfSuccessful", False),
165 ("fingerprint", "fingerprint", False),
166 ("default-excludes", "defaultExcludes", True),
167 ("case-sensitive", "caseSensitive", True),
168 ("latest-only", "latestOnly", False),
169 ("follow-symlinks", "followSymlinks", False),
170 ]
171
172 if "excludes" in data:
173 mapping.append(("excludes", "excludes", None))
174 helpers.convert_mapping_to_xml(archiver, data, mapping, fail_required=True)
175
176
177 def blame_upstream(registry, xml_parent, data):
178 """yaml: blame-upstream
179 Notify upstream committers when build fails
180
181 Requires the Jenkins :jenkins-github:`Blame Upstream Committers Plugin
182 <blame-upstream-commiters-plugin>`.
183
184 Example:
185
186 .. literalinclude:: /../../tests/publishers/fixtures/blame001.yaml
187 :language: yaml
188 """
189
190 XML.SubElement(
191 xml_parent,
192 "hudson.plugins.blame__upstream__commiters." "BlameUpstreamCommitersPublisher",
193 )
194
195
196 def jclouds(registry, xml_parent, data):
197 """yaml: jclouds
198 JClouds Cloud Storage Settings provides a way to store artifacts on
199 JClouds supported storage providers. Requires the Jenkins
200 :jenkins-plugins:`JClouds Plugin <jclouds-jenkins>`.
201
202 JClouds Cloud Storage Settings must be configured for the Jenkins instance.
203
204 :arg str profile: preconfigured storage profile (required)
205 :arg str files: files to upload (regex) (required)
206 :arg str basedir: the source file path (relative to workspace, Optional)
207 :arg str container: the destination container name (required)
208 :arg bool hierarchy: keep hierarchy (default false)
209
210 Example:
211
212 .. literalinclude:: /../../tests/publishers/fixtures/jclouds001.yaml
213
214 """
215
216 deployer = XML.SubElement(
217 xml_parent, "jenkins.plugins.jclouds.blobstore." "BlobStorePublisher"
218 )
219 entries = XML.SubElement(deployer, "entries")
220 deployer_entry = XML.SubElement(
221 entries, "jenkins.plugins.jclouds.blobstore." "BlobStoreEntry"
222 )
223 deployer_mapping = [("profile", "profileName", None)]
224 helpers.convert_mapping_to_xml(deployer, data, deployer_mapping, fail_required=True)
225 try:
226 XML.SubElement(deployer_entry, "container").text = data["container"]
227 XML.SubElement(deployer_entry, "sourceFile").text = data["files"]
228 except KeyError as e:
229 raise JenkinsJobsException("blobstore requires '%s' to be set" % e.args[0])
230 deployer_entry_mapping = [
231 ("hierarchy", "keepHierarchy", False),
232 ("basedir", "path", ""),
233 ]
234 helpers.convert_mapping_to_xml(
235 deployer_entry, data, deployer_entry_mapping, fail_required=True
236 )
237
238
239 def javadoc(registry, xml_parent, data):
240 """yaml: javadoc
241 Publish Javadoc
242 Requires the Jenkins :jenkins-plugins:`Javadoc Plugin <javadoc>`.
243
244 :arg str directory: Directory relative to the root of the workspace,
245 such as 'myproject/build/javadoc' (optional)
246 :arg bool keep-all-successful: When true, it will retain Javadoc for each
247 successful build. This allows you to browse Javadoc for older builds,
248 at the expense of additional disk space requirement. If false, it will
249 only keep the latest Javadoc, so older Javadoc will be overwritten as
250 new builds succeed. (default false)
251
252 Example:
253
254 .. literalinclude:: /../../tests/publishers/fixtures/javadoc001.yaml
255 :language: yaml
256 """
257
258 root = XML.SubElement(xml_parent, "hudson.tasks.JavadocArchiver")
259
260 mapping = [
261 ("directory", "javadocDir", None),
262 ("keep-all-successful", "keepAll", False),
263 ]
264 helpers.convert_mapping_to_xml(root, data, mapping, fail_required=False)
265
266
267 def jdepend(registry, xml_parent, data):
268 """yaml: jdepend
269 Publish jdepend report
270 Requires the :jenkins-plugins:`JDepend Plugin <jdepend>`.
271
272 :arg str file: path to jdepend file (required)
273
274 Example:
275
276 .. literalinclude:: /../../tests/publishers/fixtures/jdepend001.yaml
277 :language: yaml
278 """
279 jdepend = XML.SubElement(xml_parent, "hudson.plugins.jdepend.JDependRecorder")
280 mapping = [("file", "configuredJDependFile", None)]
281 helpers.convert_mapping_to_xml(jdepend, data, mapping, fail_required=True)
282
283
284 def hue_light(registry, xml_parent, data):
285 """yaml: hue-light
286 This plugin shows the state of your builds using the awesome Philips hue
287 lights.
288
289 Requires the Jenkins :jenkins-plugins:`hue-light Plugin
290 <hue-light>`.
291
292 :arg int light-id: ID of light. Define multiple lights by a comma as a
293 separator (required)
294 :arg str pre-build: Colour of building state (default 'blue')
295 :arg str good-build: Colour of successful state (default 'green')
296 :arg str unstable-build: Colour of unstable state (default 'yellow')
297 :arg str bad-build: Colour of unsuccessful state (default 'red')
298
299 Full Example:
300
301 .. literalinclude::
302 /../../tests/publishers/fixtures/hue-light-full.yaml
303 :language: yaml
304
305 Minimal Example:
306
307 .. literalinclude::
308 /../../tests/publishers/fixtures/hue-light-minimal.yaml
309 :language: yaml
310 """
311
312 hue_light = XML.SubElement(
313 xml_parent, "org.jenkinsci.plugins.hue__light.LightNotifier"
314 )
315 hue_light.set("plugin", "hue-light")
316 lightId = XML.SubElement(hue_light, "lightId")
317
318 id_mapping = [("light-id", "string", None)]
319 helpers.convert_mapping_to_xml(lightId, data, id_mapping, fail_required=True)
320
321 build_mapping = [
322 ("pre-build", "preBuild", "blue"),
323 ("good-build", "goodBuild", "green"),
324 ("unstable-build", "unstableBuild", "yellow"),
325 ("bad-build", "badBuild", "red"),
326 ]
327 helpers.convert_mapping_to_xml(hue_light, data, build_mapping, fail_required=True)
328
329
330 def campfire(registry, xml_parent, data):
331 """yaml: campfire
332 Send build notifications to Campfire rooms.
333 Requires the Jenkins :jenkins-plugins:`Campfire Plugin <campfire>`.
334
335 Campfire notifications global default values must be configured for
336 the Jenkins instance. Default values will be used if no specific
337 values are specified for each job, so all config params are optional.
338
339 :arg str subdomain: override the default campfire subdomain
340 :arg str token: override the default API token
341 :arg bool ssl: override the default 'use SSL'
342 :arg str room: override the default room name
343
344 Example:
345
346 .. literalinclude:: /../../tests/publishers/fixtures/campfire001.yaml
347 :language: yaml
348 """
349
350 root = XML.SubElement(xml_parent, "hudson.plugins.campfire." "CampfireNotifier")
351 campfire = XML.SubElement(root, "campfire")
352
353 mapping = [
354 ("subdomain", "subdomain", None),
355 ("token", "token", None),
356 ("ssl", "ssl", None),
357 ]
358 helpers.convert_mapping_to_xml(campfire, data, mapping, fail_required=False)
359
360 if "room" in data:
361 room = XML.SubElement(root, "room")
362 mapping = [("room", "name", None)]
363 helpers.convert_mapping_to_xml(room, data, mapping, fail_required=True)
364
365 XML.SubElement(room, 'campfire reference="../../campfire"')
366
367
368 def mqtt(registry, xml_parent, data):
369 """yaml: mqtt
370 This plugin lets you send build notifications to a MQTT message queue.
371 Requires the :jenkins-plugins:`MQTT Notification Plugin
372 <mqtt-notification-plugin>`.
373
374 :arg str broker-url: the broker URL, as protocol://address:port (required)
375 :arg str credentials-id: credentials to use to connect to the broker
376 (optional)
377 :arg str topic: the message topic (default "jenkins/$PROJECT_URL")
378 :arg str message: the message itself (default "$BUILD_RESULT")
379 :arg str qos: one of AT_MOST_ONCE, AT_LEAST_ONCE, or EXACTLY_ONCE
380 (default AT_MOST_ONCE)
381 :arg bool retain-message: whether to resend message or not when a new
382 client connects (default false)
383
384 Minimal Example:
385
386 .. literalinclude:: /../../tests/publishers/fixtures/mqtt-minimal.yaml
387 :language: yaml
388
389 Full Example:
390
391 .. literalinclude:: /../../tests/publishers/fixtures/mqtt-full.yaml
392 :language: yaml
393 """
394
395 mqtt = XML.SubElement(xml_parent, "jenkins.plugins.mqttnotification.MqttNotifier")
396 mqtt.set("plugin", "mqtt-notification-plugin")
397 mqtt_mapping = [("broker-url", "brokerUrl", None)]
398 helpers.convert_mapping_to_xml(mqtt, data, mqtt_mapping, fail_required=True)
399 mqtt_mapping = [
400 ("credentials-id", "credentialsId", None),
401 ("topic", "topic", "jenkins/$PROJECT_URL"),
402 ("message", "message", "$BUILD_RESULT"),
403 (
404 "qos",
405 "qos",
406 "AT_MOST_ONCE",
407 {"AT_MOST_ONCE": "0", "AT_LEAST_ONCE": "1", "EXACTLY_ONCE": "2"},
408 ),
409 ("retain-message", "retainMessage", False),
410 ]
411 helpers.convert_mapping_to_xml(mqtt, data, mqtt_mapping, fail_required=False)
412
413
414 def codecover(registry, xml_parent, data):
415 """yaml: codecover
416 This plugin allows you to capture code coverage report from CodeCover.
417 Jenkins will generate the trend report of coverage.
418 Requires the Jenkins :jenkins-plugins:`CodeCover Plugin <codecover>`.
419
420 :arg str include: Specify the path to the CodeCover HTML report file,
421 relative to the workspace root (default '')
422 :arg int min-statement: Minimum statement threshold (default 0)
423 :arg int max-statement: Maximum statement threshold (default 90)
424 :arg int min-branch: Minimum branch threshold (default 0)
425 :arg int max-branch: Maximum branch threshold (default 80)
426 :arg int min-loop: Minimum loop threshold (default 0)
427 :arg int max-loop: Maximum loop threshold (default 50)
428 :arg int min-condition: Minimum condition threshold (default 0)
429 :arg int max-condition: Maximum conditon threshold (default 50)
430
431 Minimal Example:
432
433 .. literalinclude::
434 /../../tests/publishers/fixtures/codecover-minimal.yaml
435 :language: yaml
436
437 Full Example:
438
439 .. literalinclude::
440 /../../tests/publishers/fixtures/codecover-full.yaml
441 :language: yaml
442 """
443
444 codecover = XML.SubElement(
445 xml_parent, "hudson.plugins.codecover.CodeCoverPublisher"
446 )
447 codecover.set("plugin", "codecover")
448
449 XML.SubElement(codecover, "includes").text = str(data.get("include", ""))
450
451 health_report = XML.SubElement(codecover, "healthReports")
452 mapping = [
453 ("min-statement", "minStatement", 0),
454 ("max-statement", "maxStatement", 90),
455 ("min-branch", "minBranch", 0),
456 ("max-branch", "maxBranch", 80),
457 ("min-loop", "minLoop", 0),
458 ("max-loop", "maxLoop", 50),
459 ("min-condition", "minCondition", 0),
460 ("max-condition", "maxCondition", 50),
461 ]
462 helpers.convert_mapping_to_xml(health_report, data, mapping, fail_required=True)
463
464
465 def emotional_jenkins(registry, xml_parent, data):
466 """yaml: emotional-jenkins
467 Emotional Jenkins. This funny plugin changes the expression of Mr. Jenkins
468 in the background when your builds fail.
469
470 Requires the Jenkins :jenkins-plugins:`Emotional Jenkins Plugin
471 <emotional-jenkins-plugin>`.
472
473 Example:
474
475 .. literalinclude::
476 /../../tests/publishers/fixtures/emotional-jenkins.yaml
477 :language: yaml
478 """
479 XML.SubElement(
480 xml_parent,
481 "org.jenkinsci.plugins.emotional__jenkins." "EmotionalJenkinsPublisher",
482 )
483
484
485 def trigger_parameterized_builds(registry, xml_parent, data):
486 """yaml: trigger-parameterized-builds
487 Trigger parameterized builds of other jobs.
488 Requires the Jenkins :jenkins-plugins:`Parameterized Trigger Plugin
489 <parameterized-trigger>`.
490
491 Use of the `node-label-name` or `node-label` parameters
492 requires the Jenkins :jenkins-plugins:`NodeLabel Parameter Plugin
493 <nodelabelparameter>`.
494 Note: 'node-parameters' overrides the Node that the triggered
495 project is tied to.
496
497 :arg list project: list the jobs to trigger, will generate comma-separated
498 string containing the named jobs.
499 :arg str predefined-parameters: parameters to pass to the other
500 job (optional)
501 :arg bool current-parameters: Whether to include the parameters passed
502 to the current build to the triggered job (optional)
503 :arg bool node-parameters: Use the same Node for the triggered builds
504 that was used for this build. (optional)
505 :arg bool svn-revision: Pass svn revision to the triggered job (optional)
506 :arg bool include-upstream: Include/pass through Upstream SVN Revisons.
507 Only valid when 'svn-revision' is true. (default false)
508 :arg dict git-revision: Passes git revision to the triggered job
509 (optional).
510
511 * **combine-queued-commits** (bool): Whether to combine queued git
512 hashes or not (default false)
513
514 :arg bool combine-queued-commits: Combine Queued git hashes. Only valid
515 when 'git-revision' is true. (default false)
516
517 .. deprecated:: 1.5.0 Please use `combine-queued-commits` under the
518 `git-revision` argument instead.
519
520 :arg dict boolean-parameters: Pass boolean parameters to the downstream
521 jobs. Specify the name and boolean value mapping of the parameters.
522 (optional)
523 :arg str condition: when to trigger the other job. Can be: 'SUCCESS',
524 'UNSTABLE', 'FAILED_OR_BETTER', 'UNSTABLE_OR_BETTER',
525 'UNSTABLE_OR_WORSE', 'FAILED', 'ALWAYS'. (default 'ALWAYS')
526 :arg str property-file: Use properties from file (optional)
527 :arg bool fail-on-missing: Blocks the triggering of the downstream jobs
528 if any of the property files are not found in the workspace.
529 Only valid when 'property-file' is specified.
530 (default 'False')
531 :arg bool property-multiline: When enabled properties containing
532 newline character(s) are propagated as TextParameterValue which is
533 a specialized StringParameterValue commonly used for handling
534 multi-line strings in Jenkins. When disabled (default)
535 all properties are propagated as StringParameterValue. (default
536 'False') (>=2.35.2)
537 :arg bool trigger-from-child-projects: Trigger build from child projects.
538 Used for matrix projects. (default 'False')
539 :arg bool use-matrix-child-files: Use files in workspaces of child
540 builds (default 'False')
541 :arg str matrix-child-combination-filter: A Groovy expression to filter
542 the child builds to look in for files
543 :arg bool only-exact-matrix-child-runs: Use only child builds triggered
544 exactly by the parent.
545 :arg str file-encoding: Encoding of contents of the files. If not
546 specified, default encoding of the platform is used. Only valid when
547 'property-file' is specified. (optional)
548 :arg bool trigger-with-no-params: Trigger a build even when there are
549 currently no parameters defined (default 'False')
550 :arg str restrict-matrix-project: Filter that restricts the subset
551 of the combinations that the downstream project will run (optional)
552 :arg str node-label-name: Specify the Name for the NodeLabel parameter.
553 (optional)
554 :arg str node-label: Specify the Node for the NodeLabel parameter.
555 (optional)
556
557 Example:
558
559 .. literalinclude::
560 /../../tests/publishers/fixtures/trigger_parameterized_builds001.yaml
561 :language: yaml
562 .. literalinclude::
563 /../../tests/publishers/fixtures/trigger_parameterized_builds003.yaml
564 :language: yaml
565 """
566 pt_prefix = "hudson.plugins.parameterizedtrigger."
567 tbuilder = XML.SubElement(xml_parent, pt_prefix + "BuildTrigger")
568 configs = XML.SubElement(tbuilder, "configs")
569
570 param_order = helpers.trigger_get_parameter_order(
571 registry, "trigger-parameterized-builds"
572 )
573
574 for project_def in data:
575 tconfig = XML.SubElement(configs, pt_prefix + "BuildTriggerConfig")
576 tconfigs = XML.SubElement(tconfig, "configs")
577
578 helpers.trigger_project(tconfigs, project_def, registry, param_order)
579
580 if not list(tconfigs):
581 # no child parameter tags added
582 tconfigs.set("class", "java.util.Collections$EmptyList")
583
584 projects = XML.SubElement(tconfig, "projects")
585
586 if isinstance(project_def["project"], list):
587 projects.text = ",".join(project_def["project"])
588 else:
589 projects.text = project_def["project"]
590
591 condition = XML.SubElement(tconfig, "condition")
592 condition.text = project_def.get("condition", "ALWAYS")
593 mapping = [
594 ("trigger-from-child-projects", "triggerFromChildProjects", False),
595 ("trigger-with-no-params", "triggerWithNoParameters", False),
596 ]
597 helpers.convert_mapping_to_xml(
598 tconfig, project_def, mapping, fail_required=False
599 )
600
601
602 def trigger(registry, xml_parent, data):
603 """yaml: trigger
604 Trigger non-parametrised builds of other jobs.
605
606 :arg str project: name of the job to trigger
607 :arg str threshold: when to trigger the other job (default 'SUCCESS'),
608 alternatives: SUCCESS, UNSTABLE, FAILURE
609
610 Example:
611
612 .. literalinclude:: /../../tests/publishers/fixtures/trigger_success.yaml
613 :language: yaml
614 """
615 tconfig = XML.SubElement(xml_parent, "hudson.tasks.BuildTrigger")
616 childProjects = XML.SubElement(tconfig, "childProjects")
617 childProjects.text = data["project"]
618
619 threshold = data.get("threshold", "SUCCESS")
620 supported_thresholds = ["SUCCESS", "UNSTABLE", "FAILURE"]
621 helpers.trigger_threshold(
622 tconfig, "threshold", threshold, supported_thresholds=supported_thresholds
623 )
624
625
626 def clone_workspace(registry, xml_parent, data):
627 """yaml: clone-workspace
628 Archive the workspace from builds of one project and reuse them as the SCM
629 source for another project.
630 Requires the Jenkins :jenkins-plugins:`Clone Workspace SCM Plugin
631 <clone-workspace-scm>`.
632
633 :arg str workspace-glob: Files to include in cloned workspace (default '')
634 :arg str workspace-exclude-glob: Files to exclude from cloned workspace
635 :arg str criteria: Criteria for build to be archived. Can be 'any',
636 'not failed', or 'successful'. (default 'any')
637 :arg str archive-method: Choose the method to use for archiving the
638 workspace. Can be 'tar' or 'zip'. (default 'tar')
639 :arg bool override-default-excludes: Override default ant excludes.
640 (default false)
641
642 Minimal example:
643
644 .. literalinclude::
645 /../../tests/publishers/fixtures/clone-workspace001.yaml
646 :language: yaml
647
648 Full example:
649
650 .. literalinclude::
651 /../../tests/publishers/fixtures/clone-workspace002.yaml
652 :language: yaml
653 """
654
655 cloneworkspace = XML.SubElement(
656 xml_parent, "hudson.plugins.cloneworkspace.CloneWorkspacePublisher"
657 )
658 cloneworkspace.set("plugin", "clone-workspace-scm")
659
660 criteria_valid_types = ["Any", "Not Failed", "Successful"]
661 archive_valid_types = ["TAR", "ZIP"]
662
663 mappings = [
664 ("workspace-glob", "workspaceGlob", ""),
665 ("override-default-excludes", "overrideDefaultExcludes", False),
666 ("criteria", "criteria", "Any", criteria_valid_types),
667 ("archive-method", "archiveMethod", "TAR", archive_valid_types),
668 ]
669 helpers.convert_mapping_to_xml(cloneworkspace, data, mappings, fail_required=True)
670
671 mappings = [("workspace-exclude-glob", "workspaceExcludeGlob", "")]
672 helpers.convert_mapping_to_xml(cloneworkspace, data, mappings, fail_required=False)
673
674
675 def cloud_foundry(parser, xml_parent, data):
676 """yaml: cloudfoundry
677 Pushes a project to Cloud Foundry or a CF-based platform (e.g. Stackato) at
678 the end of a build. Requires the Jenkins :jenkins-plugins:`Cloud Foundry
679 Plugin <cloudfoundry>`.
680
681 :arg str target: The API endpoint of the platform you want to push to.
682 This is the URL you use to access the platform, possibly with ".api"
683 added. (required)
684 :arg str organization: An org is a development account that an individual
685 or multiple collaborators can own and use (required)
686 :arg str space: Provide users with access to a shared location for
687 application development, deployment, and maintenance (required)
688 :arg str credentials-id: credentials-id of the user (required)
689 :arg bool self-signed: Allow self-signed SSL certificates from the target
690 (default false)
691 :arg bool reset-app: Delete app before pushing app's configurations
692 (default false)
693 :arg int plugin-timeout: The time in seconds before the Cloud Foundry
694 plugin stops fetching logs and marks the build a failure (default 120)
695 :arg list create-services: Create services automatically (default '')
696
697 :create-services:
698 * **name** ('str') -- Service name (default '')
699 * **type** ('str') -- Service type (default '')
700 * **plan** ('str') -- Service plan (default '')
701 * **reset-service** ('bool') -- Delete the service before creating
702 the new one (default false)
703 :arg str value: Select to read configuration from manifest file or to enter
704 configuration in Jenkins (default 'manifestFile')
705 :arg str manifest-file: Path to manifest file (default 'manifest.yml')
706 :arg str app-name: The application's name. Default to Jenkins build name.
707 (default '')
708 :arg int memory: The application's memory usage in MB (default 512)
709 :arg str host-name: The hostname of the URI to access your application.
710 Default to app-name (default '')
711 :arg int instances: Number of instances of your application on creation
712 (default 1)
713 :arg int manifest-timeout: The time in seconds before the health-manager
714 gives up on starting the application (default 60)
715 :arg bool no-route: No URI path will be created to access the application
716 (default false)
717 :arg str app-path: Path to application (default '')
718 :arg build-pack: If your application requires a custom buildpack, you can
719 use this to specify its URL or name (default '')
720 :arg str stack: If your application requires a custom stack, you can use
721 this to specify its name. (default '')
722 :arg str command: Set a custom start command for your application
723 (default '')
724 :arg str domain: The domain of the URI to access your application
725 (default '')
726 :arg list environment-variables: Inject environment variables
727
728 :environment-variables:
729 * **key** ('str') -- Environment variable key (default '')
730 * **value** ('str') -- Environment variable value (default '')
731 :arg list services-names: Name of service instances
732
733 :services-names:
734 * **name** ('str') -- Name of the service instance (default '')
735
736 Minimal example:
737
738 .. literalinclude::
739 /../../tests/publishers/fixtures/cloudfoundry-minimal.yaml
740 :language: yaml
741
742 Full example:
743
744 .. literalinclude:: /../../tests/publishers/fixtures/cloudfoundry-full.yaml
745 :language: yaml
746 """
747 cloud_foundry = XML.SubElement(
748 xml_parent, "com.hpe.cloudfoundryjenkins.CloudFoundryPushPublisher"
749 )
750 cloud_foundry.set("plugin", "cloudfoundry")
751
752 mapping = [
753 ("target", "target", None),
754 ("organization", "organization", None),
755 ("space", "cloudSpace", None),
756 ("credentials-id", "credentialsId", None),
757 ("self-signed", "selfSigned", False),
758 ("reset-app", "resetIfExists", False),
759 ("timeout", "pluginTimeout", 120),
760 ]
761 helpers.convert_mapping_to_xml(cloud_foundry, data, mapping, fail_required=True)
762 XML.SubElement(cloud_foundry, "appURIs").text = ""
763
764 create_services = XML.SubElement(cloud_foundry, "servicesToCreate")
765 create_services_mapping = [
766 ("name", "name", ""),
767 ("type", "type", ""),
768 ("plan", "plan", ""),
769 ("reset-service", "resetService", ""),
770 ]
771 for service in data.get("create-services", ""):
772 create_services_sub = XML.SubElement(
773 create_services,
774 "com.hpe.cloudfoundryjenkins.CloudFoundryPushPublisher_-Service",
775 )
776 helpers.convert_mapping_to_xml(
777 create_services_sub, service, create_services_mapping, fail_required=True
778 )
779
780 manifest = XML.SubElement(cloud_foundry, "manifestChoice")
781 valid_values = ["manifestFile", "jenkinsConfig"]
782 manifest_mapping = [
783 ("value", "value", "manifestFile", valid_values),
784 ("manifest-file", "manifestFile", "manifest.yml"),
785 ("app-name", "appName", ""),
786 ("memory", "memory", 512),
787 ("host-name", "hostname", ""),
788 ("instances", "instances", 1),
789 ("manifest-timeout", "timeout", 60),
790 ("no-route", "noRoute", False),
791 ("app-path", "appPath", ""),
792 ("build-pack", "buildpack", ""),
793 ("stack", "stack", ""),
794 ("command", "command", ""),
795 ("domain", "domain", ""),
796 ]
797 helpers.convert_mapping_to_xml(manifest, data, manifest_mapping, fail_required=True)
798
799 if "environment-variables" in data:
800 env_vars = XML.SubElement(manifest, "envVars")
801 env_vars_mapping = [("key", "key", ""), ("value", "value", "")]
802 for var in data["environment-variables"]:
803 env_vars_sub = XML.SubElement(
804 env_vars,
805 "com.hpe.cloudfoundryjenkins.CloudFoundryPushPublisher_-"
806 "EnvironmentVariable",
807 )
808 helpers.convert_mapping_to_xml(
809 env_vars_sub, var, env_vars_mapping, fail_required=True
810 )
811
812 if "services-names" in data:
813 services_names = XML.SubElement(manifest, "servicesNames")
814 service_name_mapping = [("name", "name", "")]
815 for name in data["services-names"]:
816 services_names_sub = XML.SubElement(
817 services_names,
818 "com.hpe.cloudfoundryjenkins.CloudFoundryPushPublisher_-" "ServiceName",
819 )
820 helpers.convert_mapping_to_xml(
821 services_names_sub, name, service_name_mapping, fail_required=True
822 )
823
824
825 def cloverphp(registry, xml_parent, data):
826 """yaml: cloverphp
827 Capture code coverage reports from PHPUnit
828 Requires the Jenkins :jenkins-plugins:`Clover PHP Plugin <cloverphp>`.
829
830 Your job definition should pass to PHPUnit the --coverage-clover option
831 pointing to a file in the workspace (ex: clover-coverage.xml). The filename
832 has to be filled in the `xml-location` field.
833
834 :arg str xml-location: Path to the coverage XML file generated by PHPUnit
835 using --coverage-clover. Relative to workspace. (required)
836 :arg dict html: When existent, whether the plugin should generate a HTML
837 report. Note that PHPUnit already provide a HTML report via its
838 --cover-html option which can be set in your builder (optional):
839
840 * **dir** (str): Directory where HTML report will be generated relative
841 to workspace. (required in `html` dict).
842 * **archive** (bool): Whether to archive HTML reports (default true).
843
844 :arg list metric-targets: List of metric targets to reach, must be one of
845 **healthy**, **unhealthy** and **failing**. Each metric target can
846 takes two parameters:
847
848 * **method** Target for method coverage
849 * **statement** Target for statements coverage
850
851 Whenever a metric target is not filled in, the Jenkins plugin can fill
852 in defaults for you (as of v0.3.3 of the plugin the healthy target will
853 have method: 70 and statement: 80 if both are left empty). Jenkins Job
854 Builder will mimic that feature to ensure clean configuration diff.
855
856 Minimal example:
857
858 .. literalinclude:: /../../tests/publishers/fixtures/cloverphp001.yaml
859 :language: yaml
860
861 Full example:
862
863 .. literalinclude:: /../../tests/publishers/fixtures/cloverphp002.yaml
864 :language: yaml
865 """
866 cloverphp = XML.SubElement(
867 xml_parent, "org.jenkinsci.plugins.cloverphp.CloverPHPPublisher"
868 )
869 cloverphp.set("plugin", "cloverphp")
870
871 # The plugin requires clover XML file to parse
872 if "xml-location" not in data:
873 raise JenkinsJobsException("xml-location must be set")
874
875 # Whether HTML publishing has been checked
876 html_publish = False
877 # By default, disableArchiving = false. Note that we use
878 # reversed logic.
879 html_archive = True
880
881 if "html" in data:
882 html_publish = True
883 html_dir = data["html"].get("dir", None)
884 html_archive = data["html"].get("archive", html_archive)
885 if html_dir is None:
886 # No point in going further, the plugin would not work
887 raise JenkinsJobsException("htmldir is required in a html block")
888
889 XML.SubElement(cloverphp, "publishHtmlReport").text = str(html_publish).lower()
890 if html_publish:
891 XML.SubElement(cloverphp, "reportDir").text = html_dir
892 XML.SubElement(cloverphp, "xmlLocation").text = data.get("xml-location")
893 XML.SubElement(cloverphp, "disableArchiving").text = str(not html_archive).lower()
894
895 # Handle targets
896
897 # Plugin v0.3.3 will fill defaults for us whenever healthy targets are both
898 # blanks.
899 default_metrics = {"healthy": {"method": 70, "statement": 80}}
900 allowed_metrics = ["healthy", "unhealthy", "failing"]
901
902 metrics = data.get("metric-targets", [])
903 # list of dicts to dict
904 metrics = dict(kv for m in metrics for kv in m.items())
905
906 # Populate defaults whenever nothing has been filled by user.
907 for default in default_metrics.keys():
908 if metrics.get(default, None) is None:
909 metrics[default] = default_metrics[default]
910
911 # The plugin would at least define empty targets so make sure
912 # we output them all in the XML regardless of what the user
913 # has or has not entered.
914 for target in allowed_metrics:
915 cur_target = XML.SubElement(cloverphp, target + "Target")
916
917 for t_type in ["method", "statement"]:
918 val = metrics.get(target, {}).get(t_type)
919 if val is None or type(val) is not int:
920 continue
921 if val < 0 or val > 100:
922 raise JenkinsJobsException(
923 "Publisher cloverphp metric target %s:%s = %s "
924 "is not in valid range 0-100." % (target, t_type, val)
925 )
926 XML.SubElement(cur_target, t_type + "Coverage").text = str(val)
927
928
929 def coverage(registry, xml_parent, data):
930 """yaml: coverage
931 WARNING: The coverage function is deprecated. Instead, use the
932 cobertura function to generate a cobertura coverage report.
933 Requires the Jenkins :jenkins-plugins:`Cobertura Coverage Plugin
934 <cobertura>`.
935
936 Example:
937
938 .. literalinclude:: /../../tests/publishers/fixtures/coverage001.yaml
939 :language: yaml
940 """
941 logger = logging.getLogger(__name__)
942 logger.warning("Coverage function is deprecated. Switch to cobertura.")
943
944 cobertura = XML.SubElement(
945 xml_parent, "hudson.plugins.cobertura.CoberturaPublisher"
946 )
947 XML.SubElement(cobertura, "coberturaReportFile").text = "**/coverage.xml"
948 XML.SubElement(cobertura, "onlyStable").text = "false"
949 healthy = XML.SubElement(cobertura, "healthyTarget")
950 targets = XML.SubElement(
951 healthy,
952 "targets",
953 {
954 "class": "enum-map",
955 "enum-type": "hudson.plugins.cobertura.targets.CoverageMetric",
956 },
957 )
958 entry = XML.SubElement(targets, "entry")
959 XML.SubElement(
960 entry, "hudson.plugins.cobertura.targets.CoverageMetric"
961 ).text = "CONDITIONAL"
962 XML.SubElement(entry, "int").text = "70"
963 entry = XML.SubElement(targets, "entry")
964 XML.SubElement(
965 entry, "hudson.plugins.cobertura.targets.CoverageMetric"
966 ).text = "LINE"
967 XML.SubElement(entry, "int").text = "80"
968 entry = XML.SubElement(targets, "entry")
969 XML.SubElement(
970 entry, "hudson.plugins.cobertura.targets.CoverageMetric"
971 ).text = "METHOD"
972 XML.SubElement(entry, "int").text = "80"
973 unhealthy = XML.SubElement(cobertura, "unhealthyTarget")
974 targets = XML.SubElement(
975 unhealthy,
976 "targets",
977 {
978 "class": "enum-map",
979 "enum-type": "hudson.plugins.cobertura.targets.CoverageMetric",
980 },
981 )
982 entry = XML.SubElement(targets, "entry")
983 XML.SubElement(
984 entry, "hudson.plugins.cobertura.targets.CoverageMetric"
985 ).text = "CONDITIONAL"
986 XML.SubElement(entry, "int").text = "0"
987 entry = XML.SubElement(targets, "entry")
988 XML.SubElement(
989 entry, "hudson.plugins.cobertura.targets.CoverageMetric"
990 ).text = "LINE"
991 XML.SubElement(entry, "int").text = "0"
992 entry = XML.SubElement(targets, "entry")
993 XML.SubElement(
994 entry, "hudson.plugins.cobertura.targets.CoverageMetric"
995 ).text = "METHOD"
996 XML.SubElement(entry, "int").text = "0"
997 failing = XML.SubElement(cobertura, "failingTarget")
998 targets = XML.SubElement(
999 failing,
1000 "targets",
1001 {
1002 "class": "enum-map",
1003 "enum-type": "hudson.plugins.cobertura.targets.CoverageMetric",
1004 },
1005 )
1006 entry = XML.SubElement(targets, "entry")
1007 XML.SubElement(
1008 entry, "hudson.plugins.cobertura.targets.CoverageMetric"
1009 ).text = "CONDITIONAL"
1010 XML.SubElement(entry, "int").text = "0"
1011 entry = XML.SubElement(targets, "entry")
1012 XML.SubElement(
1013 entry, "hudson.plugins.cobertura.targets.CoverageMetric"
1014 ).text = "LINE"
1015 XML.SubElement(entry, "int").text = "0"
1016 entry = XML.SubElement(targets, "entry")
1017 XML.SubElement(
1018 entry, "hudson.plugins.cobertura.targets.CoverageMetric"
1019 ).text = "METHOD"
1020 XML.SubElement(entry, "int").text = "0"
1021 XML.SubElement(cobertura, "sourceEncoding").text = "ASCII"
1022
1023
1024 def cobertura(registry, xml_parent, data):
1025 """yaml: cobertura
1026 Generate a cobertura coverage report.
1027 Requires the Jenkins :jenkins-plugins:`Cobertura Coverage Plugin
1028 <cobertura>`.
1029
1030 :arg str report-file: This is a file name pattern that can be used
1031 to locate the cobertura xml report files (optional)
1032 :arg bool only-stable: Include only stable builds (default false)
1033 :arg bool fail-no-reports: fail builds if no coverage reports are found
1034 (default false)
1035 :arg bool fail-unhealthy: Unhealthy projects will be failed (default false)
1036 :arg bool fail-unstable: Unstable projects will be failed (default false)
1037 :arg bool health-auto-update: Auto update threshold for health on
1038 successful build (default false)
1039 :arg bool stability-auto-update: Auto update threshold for stability on
1040 successful build (default false)
1041 :arg bool zoom-coverage-chart: Zoom the coverage chart and crop area below
1042 the minimum and above the maximum coverage of the past reports
1043 (default false)
1044 :arg str source-encoding: Override the source encoding (default ASCII)
1045 :arg dict targets:
1046
1047 :targets: (packages, files, classes, method, line, conditional)
1048
1049 * **healthy** (`int`): Healthy threshold (default 0)
1050 * **unhealthy** (`int`): Unhealthy threshold (default 0)
1051 * **failing** (`int`): Failing threshold (default 0)
1052
1053 Example:
1054
1055 .. literalinclude:: /../../tests/publishers/fixtures/cobertura001.yaml
1056 :language: yaml
1057 """
1058 cobertura = XML.SubElement(
1059 xml_parent, "hudson.plugins.cobertura.CoberturaPublisher"
1060 )
1061 mapping = [
1062 ("report-file", "coberturaReportFile", "**/coverage.xml"),
1063 ("only-stable", "onlyStable", False),
1064 ("fail-unhealthy", "failUnhealthy", False),
1065 ("fail-unstable", "failUnstable", False),
1066 ("health-auto-update", "autoUpdateHealth", False),
1067 ("stability-auto-update", "autoUpdateStability", False),
1068 ("zoom-coverage-chart", "zoomCoverageChart", False),
1069 ("fail-no-reports", "failNoReports", False),
1070 ]
1071 helpers.convert_mapping_to_xml(cobertura, data, mapping, fail_required=True)
1072
1073 healthy = XML.SubElement(cobertura, "healthyTarget")
1074 targets = XML.SubElement(
1075 healthy,
1076 "targets",
1077 {
1078 "class": "enum-map",
1079 "enum-type": "hudson.plugins.cobertura.targets.CoverageMetric",
1080 },
1081 )
1082 for item in data["targets"]:
1083 item_name = next(iter(item.keys()))
1084 item_values = item.get(item_name, 0)
1085 entry = XML.SubElement(targets, "entry")
1086 XML.SubElement(
1087 entry, "hudson.plugins.cobertura.targets." "CoverageMetric"
1088 ).text = str(item_name).upper()
1089 XML.SubElement(entry, "int").text = str(item_values.get("healthy", 0))
1090 unhealthy = XML.SubElement(cobertura, "unhealthyTarget")
1091 targets = XML.SubElement(
1092 unhealthy,
1093 "targets",
1094 {
1095 "class": "enum-map",
1096 "enum-type": "hudson.plugins.cobertura.targets.CoverageMetric",
1097 },
1098 )
1099 for item in data["targets"]:
1100 item_name = next(iter(item.keys()))
1101 item_values = item.get(item_name, 0)
1102 entry = XML.SubElement(targets, "entry")
1103 XML.SubElement(
1104 entry, "hudson.plugins.cobertura.targets." "CoverageMetric"
1105 ).text = str(item_name).upper()
1106 XML.SubElement(entry, "int").text = str(item_values.get("unhealthy", 0))
1107 failing = XML.SubElement(cobertura, "failingTarget")
1108 targets = XML.SubElement(
1109 failing,
1110 "targets",
1111 {
1112 "class": "enum-map",
1113 "enum-type": "hudson.plugins.cobertura.targets.CoverageMetric",
1114 },
1115 )
1116 for item in data["targets"]:
1117 item_name = next(iter(item.keys()))
1118 item_values = item.get(item_name, 0)
1119 entry = XML.SubElement(targets, "entry")
1120 XML.SubElement(
1121 entry, "hudson.plugins.cobertura.targets." "CoverageMetric"
1122 ).text = str(item_name).upper()
1123 XML.SubElement(entry, "int").text = str(item_values.get("failing", 0))
1124 XML.SubElement(cobertura, "sourceEncoding").text = data.get(
1125 "source-encoding", "ASCII"
1126 )
1127
1128
1129 def jacoco(registry, xml_parent, data):
1130 """yaml: jacoco
1131 Generate a JaCoCo coverage report.
1132 Requires the Jenkins :jenkins-plugins:`JaCoCo Plugin <jacoco>`.
1133
1134 :arg str exec-pattern: This is a file name pattern that can be used to
1135 locate the jacoco report files (default ``**/**.exec``)
1136 :arg str class-pattern: This is a file name pattern that can be used
1137 to locate class files (default ``**/classes``)
1138 :arg str source-pattern: This is a file name pattern that can be used
1139 to locate source files (default ``**/src/main/java``)
1140 :arg str source-inclusion-pattern: This is a file name pattern that can
1141 be used to include certain source files (default ``**/*.java``)
1142 :arg bool update-build-status: Update the build according to the results
1143 (default false)
1144 :arg str inclusion-pattern: This is a file name pattern that can be used
1145 to include certain class files (default '')
1146 :arg str exclusion-pattern: This is a file name pattern that can be used
1147 to exclude certain class files (default '')
1148 :arg dict targets:
1149
1150 :targets: (instruction, branch, complexity, line, method, class)
1151
1152 * **healthy** (`int`): Healthy threshold (default 0)
1153 * **unhealthy** (`int`): Unhealthy threshold (default 0)
1154
1155 Minimal Example:
1156
1157 .. literalinclude:: /../../tests/publishers/fixtures/jacoco-minimal.yaml
1158 :language: yaml
1159
1160 Full Example:
1161
1162 .. literalinclude:: /../../tests/publishers/fixtures/jacoco-full.yaml
1163 :language: yaml
1164 """
1165
1166 jacoco = XML.SubElement(xml_parent, "hudson.plugins.jacoco.JacocoPublisher")
1167 jacoco.set("plugin", "jacoco")
1168
1169 mappings = [
1170 ("exec-pattern", "execPattern", "**/**.exec"),
1171 ("class-pattern", "classPattern", "**/classes"),
1172 ("source-pattern", "sourcePattern", "**/src/main/java"),
1173 ("source-inclusion-pattern", "sourceInclusionPattern", "**/*.java"),
1174 ("update-build-status", "changeBuildStatus", False),
1175 ("inclusion-pattern", "inclusionPattern", ""),
1176 ("exclusion-pattern", "exclusionPattern", ""),
1177 ]
1178 helpers.convert_mapping_to_xml(jacoco, data, mappings, fail_required=True)
1179
1180 itemsList = ["instruction", "branch", "complexity", "line", "method", "class"]
1181
1182 if "targets" in data:
1183 for item in data["targets"]:
1184 item_name = next(iter(item.keys()))
1185 if item_name not in itemsList:
1186 raise InvalidAttributeError("targets", item_name, itemsList)
1187
1188 item_values = item[item_name]
1189 if item_values:
1190 XML.SubElement(
1191 jacoco, "maximum" + item_name.capitalize() + "Coverage"
1192 ).text = str(item_values.get("healthy", 0))
1193 XML.SubElement(
1194 jacoco, "minimum" + item_name.capitalize() + "Coverage"
1195 ).text = str(item_values.get("unhealthy", 0))
1196 else:
1197 raise MissingAttributeError(
1198 ["healthy", "unhealthy"], "publishers.jacoco.targets." + item_name
1199 )
1200
1201
1202 def ftp(registry, xml_parent, data):
1203 """yaml: ftp
1204 Upload files via FTP.
1205 Requires the Jenkins :jenkins-plugins:`Publish over FTP Plugin
1206 <publish-over-ftp>`.
1207
1208 :arg str site: name of the ftp site (required)
1209 :arg str target: destination directory (required)
1210 :arg bool target-is-date-format: whether target is a date format. If true,
1211 raw text should be quoted (default false)
1212 :arg bool clean-remote: should the remote directory be deleted before
1213 transferring files (default false)
1214 :arg str source: source path specifier (required)
1215 :arg str excludes: excluded file pattern (optional)
1216 :arg str remove-prefix: prefix to remove from uploaded file paths
1217 (optional)
1218 :arg bool fail-on-error: fail the build if an error occurs (default false).
1219 :arg bool flatten: only create files on the server, don't create
1220 directories (default false).
1221 :arg bool verbose: adds lots of detail useful for debug to the console
1222 but generally should be left off (default false)
1223 :arg int retries: the number of times to retry this server in the event of
1224 failure (optional)
1225 :arg int retry-delay: the time to wait, in milliseconds, before attempting
1226 another transfer (default 10000)
1227
1228 Minimal Example:
1229
1230 .. literalinclude:: /../../tests/publishers/fixtures/ftp-minimal.yaml
1231 :language: yaml
1232
1233 Full Example:
1234
1235 .. literalinclude:: /../../tests/publishers/fixtures/ftp-full.yaml
1236 :language: yaml
1237
1238 """
1239 console_prefix = "FTP: "
1240 plugin_tag = "jenkins.plugins.publish__over__ftp.BapFtpPublisherPlugin"
1241 publisher_tag = "jenkins.plugins.publish__over__ftp.BapFtpPublisher"
1242 transfer_tag = "jenkins.plugins.publish__over__ftp.BapFtpTransfer"
1243 retry_tag = "jenkins.plugins.publish_over_ftp.BapFtpRetry"
1244 plugin_reference_tag = "jenkins.plugins.publish_over_ftp." "BapFtpPublisherPlugin"
1245 (_, transfer_node) = base_publish_over(
1246 xml_parent,
1247 data,
1248 console_prefix,
1249 plugin_tag,
1250 publisher_tag,
1251 transfer_tag,
1252 retry_tag,
1253 plugin_reference_tag,
1254 )
1255 mapping = [("", "asciiMode", "false")]
1256 helpers.convert_mapping_to_xml(transfer_node, data, mapping, fail_required=True)
1257
1258
1259 def ftp_publisher(registry, xml_parent, data):
1260 """yaml: ftp-publisher
1261 This plugin can be used to upload project artifacts and whole directories
1262 to an ftp server.
1263 Requires the Jenkins :jenkins-plugins:`FTP-Publisher Plugin
1264 <ftppublisher>`.
1265
1266 :arg list uploads: List of files to upload
1267
1268 :uploads:
1269 * **file-path** ('str') -- Destination folder. It will be created
1270 if doesn't exists. Created relative to ftp root directory.
1271 (default '')
1272 * **source-file** ('str') -- Source files which will be uploaded
1273 (default '')
1274 :arg str site-name: Name of FTP server to upload to (required)
1275 :arg bool use-timestamps: Use timestamps in the FTP directory path (default
1276 false)
1277 :arg bool flatten-files: Flatten files on the FTP host (default false)
1278 :arg bool skip-publishing: Skip publishing (default false)
1279
1280 Minimal Example:
1281
1282 .. literalinclude::
1283 /../../tests/publishers/fixtures/ftp-publisher-minimal.yaml
1284 :language: yaml
1285
1286 Full Example:
1287
1288 .. literalinclude::
1289 /../../tests/publishers/fixtures/ftp-publisher-full.yaml
1290 :language: yaml
1291 """
1292 ftp = XML.SubElement(xml_parent, "com.zanox.hudson.plugins.FTPPublisher")
1293 ftp.set("plugin", "ftppublisher")
1294
1295 entries = XML.SubElement(ftp, "entries")
1296 if "uploads" in data:
1297 upload_mapping = [
1298 ("file-path", "filePath", ""),
1299 ("source-file", "sourceFile", ""),
1300 ]
1301 for upload in data["uploads"]:
1302 entry = XML.SubElement(entries, "com.zanox.hudson.plugins.Entry")
1303 helpers.convert_mapping_to_xml(
1304 entry, upload, upload_mapping, fail_required=True
1305 )
1306
1307 mapping = [
1308 ("site-name", "siteName", None),
1309 ("use-timestamps", "useTimestamps", False),
1310 ("flatten-files", "flatten", False),
1311 ("skip-publishing", "skip", False),
1312 ]
1313 helpers.convert_mapping_to_xml(ftp, data, mapping, fail_required=True)
1314
1315
1316 def opsgenie(registry, xml_parent, data):
1317 """yaml: opsgenie
1318 OpsGenie notification on build completion,
1319 Requires the :jenkins-plugins:`OpsGenie Notifier Plugin <opsgenie>`.
1320
1321 :arg bool enable-sending-alerts: Send alerts to opsgenie. (default false)
1322 :arg bool notify-build-start: Send a notification when the build starts. (default false)
1323 :arg str api-key: This token is used to verify requests between OpsGenie and Jenkins. You can copy this key from your OpsGenie-Jenkins Integration page. (default '')
1324 :arg str tags: Comma-separated list of tags you want to add on alert. (default '')
1325 :arg str teams: Comma-separated list of teams that get notified from alert. (default '')
1326 :arg str priority: Set the priority of the alert that's going to be created at OpsGenie, if job's build fails. (default 'P3')
1327 :arg str build-starts-alerts-priority: Set the priority of the build started alert that's going to be created at OpsGenie. (default 'P3')
1328 :arg str api-url: Api url that collects the webhook. (default '')
1329
1330 Minimal example:
1331
1332 .. literalinclude::
1333 /../../tests/publishers/fixtures/opsgenie-minimal.yaml
1334 :language: yaml
1335
1336 Full Example:
1337
1338 .. literalinclude::
1339 /../../tests/publishers/fixtures/opsgenie-full.yaml
1340 :language: yaml
1341 """
1342
1343 mapping = [
1344 ("priority", "alertPriority", "P3"),
1345 ("build-starts-alerts-priority", "notifyBuildStartPriority", "P3"),
1346 ("enable-sending-alerts", "enable", "false"),
1347 ("notify-build-start", "notifyBuildStart", "false"),
1348 ("api-key", "apiKey", ""),
1349 ("api-url", "apiUrl", ""),
1350 ("tags", "tags", ""),
1351 ("teams", "teams", ""),
1352 ]
1353
1354 opsgenie_notifier = XML.SubElement(
1355 xml_parent,
1356 "com.opsgenie.integration.jenkins.OpsGenieNotifier",
1357 {"plugin": "opsgenie"},
1358 )
1359
1360 helpers.convert_mapping_to_xml(opsgenie_notifier, data, mapping, fail_required=True)
1361
1362
1363 def rocket(registry, xml_parent, data):
1364 """yaml: rocket
1365 RocketChat notification on build completion,
1366 Requires the :jenkins-plugins:`RocketChat Notifier Plugin
1367 <rocketchatnotifier>`.
1368
1369 :arg str channel: Comma separated list of rooms (e.g. #project)
1370 or persons (e.g. @john)
1371 :arg bool abort: Notify abort (default false)
1372 :arg bool start: Notify start (default false)
1373 :arg bool success: Notify success (default false)
1374 :arg bool failure: Notify failure (default false)
1375 :arg bool repeated-failure: Notify repeated failure (default false)
1376 :arg bool back-to-normal: Notify back to normal (default false)
1377 :arg bool not-built: Notify if not built (default false)
1378 :arg bool unstable: Notify if unstable (default false)
1379 :arg str webhook-token: Webhook token for posting messages.
1380 Overrides global authentication data and channel
1381 :arg str commit-info: What commit information to include into
1382 notification message.
1383
1384 :commit-info values:
1385 * **none**
1386 * **authors**
1387 * **authors-and-titles**
1388
1389 :arg str custom-message: Custom text message (default '')
1390 :arg bool trust-ssl: Trust RocketChat server certificate, if checked,
1391 the SSL certificate will not be checked (default false)
1392 :arg str build-server: Build Server URL
1393 :arg list attachments: Optional list of attachments
1394
1395 :attachments:
1396 * **title** (`str`) Attachment title (required)
1397 * **title-link** (`str`)
1398 * **title-link-download** (`bool`)
1399 * **color** (`str`)
1400 * **text** (`str`)
1401 * **collapsed** (`bool`)
1402 * **message-link** (`str`)
1403 * **author-name** (`str`)
1404 * **author-link** (`str`)
1405 * **author-icon** (`str`)
1406 * **thumb** (`str`) Thumb URL
1407 * **image** (`str`) Image URL
1408 * **audio** (`str`) Audio URL
1409 * **video** (`str`) Video URL
1410
1411 Minimal example using defaults:
1412
1413 .. literalinclude:: /../../tests/publishers/fixtures/rocket001.yaml
1414 :language: yaml
1415
1416 Full example:
1417
1418 .. literalinclude:: /../../tests/publishers/fixtures/rocket002.yaml
1419 :language: yaml
1420 """
1421 rocketchat = XML.SubElement(
1422 xml_parent, "jenkins.plugins.rocketchatnotifier.RocketChatNotifier"
1423 )
1424 rocketchat.set("plugin", "rocketchatnotifier")
1425 required_mapping = [
1426 ("channel", "channel", ""),
1427 ("start", "startNotification", False),
1428 ("success", "notifySuccess", False),
1429 ("abort", "notifyAborted", False),
1430 ("not-built", "notifyNotBuilt", False),
1431 ("unstable", "notifyUnstable", False),
1432 ("failure", "notifyFailure", False),
1433 ("back-to-normal", "notifyBackToNormal", False),
1434 ("repeated-failure", "notifyRepeatedFailure", False),
1435 ("include-test-summary", "includeTestSummary", False),
1436 ("include-test-log", "includeTestLog", False),
1437 ("include-custom-message", "includeCustomMessage", False),
1438 (
1439 "commit-info",
1440 "commitInfoChoice",
1441 "none",
1442 {
1443 "none": "NONE",
1444 "authors": "AUTHORS",
1445 "authors-and-titles": "AUTHORS_AND_TITLES",
1446 },
1447 ),
1448 ("raw-message", "rawMessage", False),
1449 ("webhook-token", "webhookToken", ""),
1450 ("webhook-token-credential-id", "webhookTokenCredentialId", ""),
1451 ]
1452 optional_mapping = [
1453 ("trust-ssl", "trustSSL", None),
1454 ("build-server", "buildServerUrl", None),
1455 ]
1456
1457 helpers.convert_mapping_to_xml(
1458 rocketchat, data, optional_mapping, fail_required=False
1459 )
1460 helpers.convert_mapping_to_xml(
1461 rocketchat, data, required_mapping, fail_required=True
1462 )
1463
1464 attach_required_mapping = [("title", "title", None)]
1465 attach_optional_mapping = [
1466 ("title-link", "titleLink", None),
1467 ("title-link-download", "titleLinkDownload", None),
1468 ("color", "color", None),
1469 ("text", "text", None),
1470 ("collapsed", "collapsed", None), # false | true
1471 ("message-link", "messageLink", None),
1472 ("author-name", "authorName", None),
1473 ("author-link", "authorLink", None),
1474 ("author-icon", "authorIcon", None),
1475 ("thumb", "thumbUrl", None),
1476 ("image", "imageUrl", None),
1477 ("audio", "audioUrl", None),
1478 ("video", "videoUrl", None),
1479 ]
1480 attach_list = data.get("attachments", None)
1481
1482 attachments = XML.SubElement(rocketchat, "attachments")
1483 if attach_list is not None:
1484 for attach_data in attach_list:
1485 item = XML.SubElement(
1486 attachments,
1487 "jenkins.plugins.rocketchatnotifier.model.MessageAttachment",
1488 )
1489 helpers.convert_mapping_to_xml(
1490 item, attach_data, attach_required_mapping, fail_required=True
1491 )
1492 helpers.convert_mapping_to_xml(
1493 item, attach_data, attach_optional_mapping, fail_required=False
1494 )
1495
1496 XML.SubElement(rocketchat, "customMessage").text = data.get("custom-message", "")
1497
1498
1499 def hp_alm(registry, xml_parent, data):
1500 """yaml: hp-alm
1501 Publish test results to HP-ALM.
1502
1503 Requires the Jenkins :jenkins-plugins:`Micro Focus Application Automation
1504 Tools <hp-application-automation-tools-plugin>`.
1505
1506 :arg str server-name: The name of the ALM Server. (required)
1507 :arg str credentials-id: credentials-id of the user (default '')
1508 :arg str domaine: The Domain of the project to be used. (required)
1509 :arg str client-type: Client type is required for some ALM above 12.60
1510 in authentication.(default '')
1511 :arg str project: The project to be used. (required)
1512 :arg str testing-framework: The testing framework that is used when
1513 generate the testing result file. (default Junit)
1514 :arg str testing-tool: The testing tool that is used when generate
1515 the testing result file. (default '')
1516 :arg str folder: The path of the test folder that will contain
1517 the uploaded test.
1518 The path doesn't include the Root test folder (Subject).
1519 For example, sampletestfolder/subfolder means, the tests will be
1520 uploaded to test folder named 'subfolder', which is under
1521 the test folder named 'sampletestfolder', and 'sampletestfolder'
1522 is under the root test folder 'Subject'. (required)
1523 :arg str set-folder: The path of the testset folder that will contain
1524 the uploaded testset. The path doesn't include the Root testset folder.
1525 For example, sampletestsetfolder/subfolder means, the testsets will be
1526 uploaded to testset folder named 'subfolder', which is under
1527 the testset folder named 'sampletestsetfolder',
1528 and 'sampletestsetfolder' is under the root testset folder 'Root'.
1529 (required)
1530 :arg str testing-result-file: The condition to find the testing
1531 result file, start from the root path of the job.
1532 For example, ``**/junitResult.xml`` to find testing result file
1533 for Junit Plugin, ``**/testng-results.xml`` to find
1534 testing result file for TestNG plugin. (required)
1535 :arg str jenkins-server-url: The HTTP URL of the Jenkins Server,
1536 form example, http://jenkins.example.org:8080 . (optional)
1537
1538 Minimal example using defaults:
1539
1540 .. literalinclude:: /../../tests/publishers/fixtures/hp-alm001.yaml
1541 :language: yaml
1542
1543 Full example:
1544
1545 .. literalinclude:: /../../tests/publishers/fixtures/hp-alm002.yaml
1546 :language: yaml
1547 """
1548 alm_uploader = XML.SubElement(
1549 xml_parent,
1550 "com.microfocus.application.automation."
1551 "tools.results.TestResultToALMUploader",
1552 )
1553 alm_uploader.set("plugin", "hp-application-automation-tools-plugin")
1554 mapping = [
1555 ("server-name", "almServerName", None),
1556 ("credentials-id", "credentialsId", ""),
1557 ("domain", "almDomain", None),
1558 ("project", "almProject", None),
1559 ("client-type", "clientType", ""),
1560 ("testing-framework", "testingFramework", "JUnit"),
1561 ("testing-tool", "testingTool", ""),
1562 ("folder", "almTestFolder", None),
1563 ("set-folder", "almTestSetFolder", None),
1564 ("testing-result-file", "testingResultFile", None),
1565 ("jenkins-server-url", "jenkinsServerUrl", ""),
1566 ]
1567 helpers.convert_mapping_to_xml(alm_uploader, data, mapping, fail_required=True)
1568
1569
1570 def junit(registry, xml_parent, data):
1571 """yaml: junit
1572 Publish JUnit test results. Requires the Jenkins :jenkins-plugins:`JUnit
1573 Plugin <junit>`.
1574
1575 :arg str results: results filename (required)
1576 :arg bool keep-long-stdio: Retain long standard output/error in test
1577 results (default true).
1578 :arg float health-scale-factor: Amplification factor to apply to test
1579 failures when computing the test result contribution to the build
1580 health score. (default 1.0)
1581 :arg bool allow-empty-results: Do not fail the build on empty test results
1582 (default false)
1583 :arg bool skip-publishing-checks: Do not publish issues to SCM provider
1584 platforms (default false)
1585 :arg bool skip-marking-build-unstable: Do not mark build as unstable on
1586 test failure (default false)
1587 :arg bool test-stability: Add historical information about test
1588 results stability (default false).
1589 Requires the Jenkins :jenkins-plugins:`Test stability Plugin
1590 <test-stability>`.
1591 :arg bool claim-build: Allow claiming of failed tests (default false)
1592 Requires the Jenkins :jenkins-plugins:`Claim Plugin <claim>`.
1593 :arg bool measurement-plots: Create measurement plots (default false)
1594 Requires the Jenkins :jenkins-github:`Measurement Plots Plugin
1595 <measurement-plots-plugin>`.
1596 :arg bool flaky-test-reports: Publish flaky test reports (default false).
1597 Requires the Jenkins :jenkins-plugins:`Flaky Test Handler Plugin
1598 <flaky-test-handler>`.
1599 :arg bool junit-attachments: Publish test attachments (default false).
1600 Requires the Jenkins :jenkins-plugins:`JUnit Attachments Plugin
1601 <junit-attachments>`.
1602
1603
1604 Minimal example using defaults:
1605
1606 .. literalinclude:: /../../tests/publishers/fixtures/junit001.yaml
1607 :language: yaml
1608
1609 Full example:
1610
1611 .. literalinclude:: /../../tests/publishers/fixtures/junit002.yaml
1612 :language: yaml
1613 """
1614 junitresult = XML.SubElement(xml_parent, "hudson.tasks.junit.JUnitResultArchiver")
1615 junitresult.set("plugin", "junit")
1616 mapping = [
1617 ("results", "testResults", None),
1618 ("keep-long-stdio", "keepLongStdio", True),
1619 ("health-scale-factor", "healthScaleFactor", "1.0"),
1620 ("allow-empty-results", "allowEmptyResults", False),
1621 ("skip-publishing-checks", "skipPublishingChecks", False),
1622 ("skip-marking-build-unstable", "skipMarkingBuildUnstable", False),
1623 ]
1624 helpers.convert_mapping_to_xml(junitresult, data, mapping, fail_required=True)
1625
1626 datapublisher = XML.SubElement(junitresult, "testDataPublishers")
1627 if str(data.get("test-stability", False)).lower() == "true":
1628 XML.SubElement(
1629 datapublisher,
1630 "de.esailors.jenkins.teststability" ".StabilityTestDataPublisher",
1631 )
1632 if str(data.get("claim-build", False)).lower() == "true":
1633 XML.SubElement(datapublisher, "hudson.plugins.claim.ClaimTestDataPublisher")
1634 if str(data.get("measurement-plots", False)).lower() == "true":
1635 XML.SubElement(
1636 datapublisher, "hudson.plugins.measurement__plots.TestDataPublisher"
1637 )
1638 if str(data.get("flaky-test-reports", False)).lower() == "true":
1639 XML.SubElement(
1640 datapublisher,
1641 "com.google.jenkins.flakyTestHandler.plugin" ".JUnitFlakyTestDataPublisher",
1642 )
1643 if str(data.get("junit-attachments", False)).lower() == "true":
1644 XML.SubElement(
1645 datapublisher, "hudson.plugins.junitattachments.AttachmentPublisher"
1646 )
1647
1648
1649 def cucumber_reports(registry, xml_parent, data):
1650 """yaml: cucumber-reports
1651 This plugin creates pretty cucumber-jvm html reports on jenkins.
1652
1653 Requires the Jenkins :jenkins-plugins:`cucumber reports
1654 <cucumber-reports>`.
1655
1656 :arg str json-reports-path: The path relative to the workspace of
1657 the json reports generated by cucumber-jvm e.g. target - leave
1658 empty to scan the whole workspace (default '')
1659 :arg str file-include-pattern: Include pattern (default '')
1660 :arg str file-exclude-pattern: Exclude pattern (default '')
1661 :arg str plugin-url-path: The path to the jenkins user content url
1662 e.g. :samp:`http://host:port[/jenkins/]plugin` - leave empty if jenkins
1663 url root is host:port (default '')
1664 :arg bool skipped-fails: Skipped steps to cause the build to fail
1665 (default false)
1666 :arg bool pending-fails: Pending steps to cause the build to fail
1667 (default false)
1668 :arg bool undefined-fails: Undefined steps to cause the build to fail
1669 (default false)
1670 :arg bool missing-fails: Missing steps to cause the build to fail
1671 (default false)
1672 :arg bool no-flash-charts: Use javascript charts instead of flash charts
1673 (default false)
1674 :arg bool ignore-failed-tests: Entire build to fail when these tests fail
1675 (default false)
1676 :arg bool parallel-testing: Run same test in parallel for multiple devices
1677 (default false)
1678 :arg int failed-steps-number: Maximum number of failed steps above which
1679 build result is changed (default 0)
1680 :arg int skipped-steps-number: Maximum number of skipped steps above which
1681 build result is changed (default 0)
1682 :arg int pending-steps-number: Maximum number of pending steps above which
1683 build result is changed (default 0)
1684 :arg int undefined-steps-number: Maximum number of undefined steps above
1685 which build result is changed (default 0)
1686 :arg int failed-scenarios-number: Maximum number of failed scenarios above
1687 which build result is changed (default 0)
1688 :arg int failed-features-number: Maximum number of failed features above
1689 which build result is changed (default 0)
1690 :arg list build-status: Build result to which the build should be set
1691 when the report becomes failed or unstable (default '')
1692 :arg int trends-limit: Number of past reports that should be presented.
1693 Zero means unlimited number of builds (default 0)
1694 :arg list sorting-method: Result sorting order (default 'NATURAL')
1695
1696 Full example:
1697
1698 .. literalinclude::
1699 /../../tests/publishers/fixtures/cucumber-reports-full.yaml
1700 :language: yaml
1701
1702 Minimal Example:
1703
1704 .. literalinclude::
1705 /../../tests/publishers/fixtures/cucumber-reports-minimal.yaml
1706 :language: yaml
1707 """
1708 cucumber_reports = XML.SubElement(
1709 xml_parent, "net.masterthought.jenkins." "CucumberReportPublisher"
1710 )
1711 cucumber_reports.set("plugin", "cucumber-reports")
1712
1713 valid_build_status = ["", "UNSTABLE", "FAILURE"]
1714 valid_sorting_method = ["NATURAL", "ALPHABETICAL"]
1715 mappings = [
1716 ("json-reports-path", "jsonReportDirectory", ""),
1717 ("plugin-url-path", "pluginUrlPath", ""),
1718 ("file-include-pattern", "fileIncludePattern", ""),
1719 ("file-exclude-pattern", "fileExcludePattern", ""),
1720 ("skipped-fails", "skippedFails", False),
1721 ("pending-fails", "pendingFails", False),
1722 ("undefined-fails", "undefinedFails", False),
1723 ("missing-fails", "missingFails", False),
1724 ("no-flash-charts", "noFlashCharts", False),
1725 ("ignore-failed-tests", "ignoreFailedTests", False),
1726 ("parallel-testing", "parallelTesting", False),
1727 ("failed-steps-number", "failedStepsNumber", 0),
1728 ("skipped-steps-number", "skippedStepsNumber", 0),
1729 ("pending-steps-number", "pendingStepsNumber", 0),
1730 ("undefined-steps-number", "undefinedStepsNumber", 0),
1731 ("failed-scenarios-number", "failedScenariosNumber", 0),
1732 ("failed-features-number", "failedFeaturesNumber", 0),
1733 ("build-status", "buildStatus", "", valid_build_status),
1734 ("trends-limit", "trendsLimit", 0),
1735 ("sorting-method", "sortingMethod", "NATURAL", valid_sorting_method),
1736 ]
1737 helpers.convert_mapping_to_xml(cucumber_reports, data, mappings, fail_required=True)
1738
1739 if "sorting-values" in data:
1740 format_dict = {
1741 "classifications": "net.masterthought.jenkins"
1742 ".CucumberReportPublisher_-Classification"
1743 }
1744 classifications_tag = XML.SubElement(cucumber_reports, "classifications")
1745 for values in data["sorting-values"]:
1746 for value, params in values.items():
1747 cucumber_report_publisher = XML.SubElement(
1748 classifications_tag, format_dict.get("classifications")
1749 )
1750 XML.SubElement(cucumber_report_publisher, "key").text = params.get(
1751 "key"
1752 )
1753 XML.SubElement(cucumber_report_publisher, "value").text = params.get(
1754 "value"
1755 )
1756
1757
1758 def cucumber_testresult(registry, xml_parent, data):
1759 """yaml: cucumber-testresult
1760 Publish cucumber test results.
1761 Requires the Jenkins :jenkins-plugins:`Cucumber testresult
1762 <cucumber-testresult-plugin>`.
1763
1764 :arg str results: Results filename (required)
1765 :arg bool ignore-bad-steps: Ignore not existed step results (default false)
1766
1767 Minimal example:
1768
1769 .. literalinclude::
1770 /../../tests/publishers/fixtures/cucumber-testresult-minimal.yaml
1771 :language: yaml
1772
1773 Full Example:
1774
1775 .. literalinclude::
1776 /../../tests/publishers/fixtures/cucumber-testresult-full.yaml
1777 :language: yaml
1778 """
1779 cucumber_result = XML.SubElement(
1780 xml_parent,
1781 "org.jenkinsci.plugins.cucumber."
1782 "jsontestsupport."
1783 "CucumberTestResultArchiver",
1784 )
1785 cucumber_result.set("plugin", "cucumber-testresult-plugin")
1786
1787 mappings = [
1788 ("results", "testResults", None),
1789 ("ignore-bad-steps", "ignoreBadSteps", False),
1790 ]
1791 helpers.convert_mapping_to_xml(cucumber_result, data, mappings, fail_required=True)
1792
1793
1794 def xunit(registry, xml_parent, data):
1795 """yaml: xunit
1796 Publish tests results. Requires the Jenkins :jenkins-plugins:`xUnit Plugin
1797 <xunit>`.
1798
1799 :arg str thresholdmode: Whether thresholds represents an absolute number
1800 of tests or a percentage. Either 'number' or 'percent'. (default
1801 'number')
1802 :arg list thresholds: Thresholds for both 'failed' and 'skipped' tests.
1803
1804 :threshold (`dict`): Threshold values to set, where missing, xUnit
1805 should default to an internal value of 0. Each test threshold
1806 should contain the following:
1807
1808 * **unstable** (`int`)
1809 * **unstablenew** (`int`)
1810 * **failure** (`int`)
1811 * **failurenew** (`int`)
1812
1813 :arg int test-time-margin: Give the report time margin value in ms, before
1814 to fail if not new unless the option **requireupdate** is set for the
1815 configured framework. (default 3000)
1816 :arg list types: Frameworks to configure, and options. Supports the
1817 following: ``aunit``, ``boosttest``, ``checktype``, ``cpptest``,
1818 ``cppunit``, ``ctest``, ``dotnettest``, ``embunit``, ``fpcunit``,
1819 ``gtest``, ``junit``, ``mstest``, ``nunit``, ``phpunit``, ``tusar``,
1820 ``unittest``, and ``valgrind``.
1821
1822 The 'custom' type is not supported.
1823
1824 :type (`dict`): each type can be configured using the following:
1825
1826 * **pattern** (`str`): An Ant pattern to look for Junit result
1827 files, relative to the workspace root (default '')
1828 * **requireupdate** (`bool`): fail the build whenever fresh tests
1829 results have not been found (default true).
1830 * **deleteoutput** (`bool`): delete temporary JUnit files
1831 (default true).
1832 * **skip-if-no-test-files** (`bool`): Skip parsing this xUnit type
1833 report if there are no test reports files (default false).
1834 * **stoponerror** (`bool`): Fail the build whenever an error occur
1835 during a result file processing (default true).
1836
1837 Example:
1838
1839 .. literalinclude:: /../../tests/publishers/fixtures/xunit001.yaml
1840 :language: yaml
1841
1842 """
1843 plugin_ver = registry.get_plugin_version("xunit")
1844
1845 logger = logging.getLogger(__name__)
1846 xunit = XML.SubElement(xml_parent, "xunit")
1847 xunit.set("plugin", "xunit")
1848
1849 # Map our internal types to the XML element names used by Jenkins plugin
1850 types_to_plugin_types = {
1851 "aunit": "AUnitJunitHudsonTestType",
1852 "boosttest": "BoostTestJunitHudsonTestType",
1853 "checktype": "CheckType",
1854 "cpptest": "CppTestJunitHudsonTestType",
1855 "cppunit": "CppUnitJunitHudsonTestType",
1856 "ctest": "CTestType",
1857 "dotnettest": "XUnitDotNetTestType", # since plugin v1.93
1858 "embunit": "EmbUnitType", # since plugin v1.84
1859 "fpcunit": "FPCUnitJunitHudsonTestType",
1860 "gtest": "GoogleTestType",
1861 "junit": "JUnitType",
1862 "mstest": "MSTestJunitHudsonTestType",
1863 "nunit": "NUnitJunitHudsonTestType",
1864 "phpunit": "PHPUnitJunitHudsonTestType",
1865 "tusar": "TUSARJunitHudsonTestType",
1866 "unittest": "UnitTestJunitHudsonTestType",
1867 "valgrind": "ValgrindJunitHudsonTestType",
1868 # FIXME should implement the 'custom' type
1869 }
1870 implemented_types = types_to_plugin_types.keys() # shortcut
1871
1872 # Unit framework we are going to generate xml for
1873 supported_types = []
1874
1875 for configured_type in data["types"]:
1876 type_name = next(iter(configured_type.keys()))
1877 if type_name not in implemented_types:
1878 logger.warning("Requested xUnit type '%s' is not yet supported", type_name)
1879 else:
1880 # Append for generation
1881 supported_types.append(configured_type)
1882
1883 # Generate XML for each of the supported framework types
1884 # Note: versions 3+ are now using the 'tools' sub-element instead of 'types'
1885 if plugin_ver < "3.0.0":
1886 types_name = "types"
1887 else:
1888 types_name = "tools"
1889
1890 xmltypes = XML.SubElement(xunit, types_name)
1891 for supported_type in supported_types:
1892 framework_name = next(iter(supported_type.keys()))
1893 xmlframework = XML.SubElement(xmltypes, types_to_plugin_types[framework_name])
1894
1895 mappings = [
1896 ("pattern", "pattern", ""),
1897 ("requireupdate", "failIfNotNew", True),
1898 ("deleteoutput", "deleteOutputFiles", True),
1899 ("skip-if-no-test-files", "skipNoTestFiles", False),
1900 ("stoponerror", "stopProcessingIfError", True),
1901 ]
1902 helpers.convert_mapping_to_xml(
1903 xmlframework, supported_type[framework_name], mappings, fail_required=True
1904 )
1905
1906 xmlthresholds = XML.SubElement(xunit, "thresholds")
1907 for t in data.get("thresholds", []):
1908 if not ("failed" in t or "skipped" in t):
1909 logger.warning("Unrecognized threshold, should be 'failed' or 'skipped'")
1910 continue
1911 elname = (
1912 "org.jenkinsci.plugins.xunit.threshold.%sThreshold"
1913 % next(iter(t.keys())).title()
1914 )
1915 el = XML.SubElement(xmlthresholds, elname)
1916 for threshold_name, threshold_value in next(iter(t.values())).items():
1917 # Normalize and craft the element name for this threshold
1918 elname = "%sThreshold" % threshold_name.lower().replace("new", "New")
1919 XML.SubElement(el, elname).text = str(threshold_value)
1920
1921 # Whether to use percent of exact number of tests.
1922 # Thresholdmode is either:
1923 # - 1 : absolute (number of tests), default.
1924 # - 2 : relative (percentage of tests)
1925 thresholdmode = "1"
1926 if "percent" == data.get("thresholdmode", "number"):
1927 thresholdmode = "2"
1928 XML.SubElement(xunit, "thresholdMode").text = thresholdmode
1929
1930 extra_config = XML.SubElement(xunit, "extraConfiguration")
1931 XML.SubElement(extra_config, "testTimeMargin").text = str(
1932 data.get("test-time-margin", "3000")
1933 )
1934
1935
1936 def _violations_add_entry(xml_parent, name, data):
1937 vmin = data.get("min", 10)
1938 vmax = data.get("max", 999)
1939 vunstable = data.get("unstable", 999)
1940 pattern = data.get("pattern", None)
1941
1942 entry = XML.SubElement(xml_parent, "entry")
1943 mapping = [("", "string", name)]
1944 helpers.convert_mapping_to_xml(entry, data, mapping, fail_required=True)
1945
1946 tconfig = XML.SubElement(entry, "hudson.plugins.violations.TypeConfig")
1947 mapping = [
1948 ("", "type", name),
1949 ("", "min", str(vmin)),
1950 ("", "max", str(vmax)),
1951 ("", "unstable", str(vunstable)),
1952 ("", "usePattern", "false"),
1953 ]
1954 helpers.convert_mapping_to_xml(tconfig, data, mapping, fail_required=True)
1955
1956 if pattern:
1957 XML.SubElement(tconfig, "pattern").text = pattern
1958 else:
1959 XML.SubElement(tconfig, "pattern")
1960
1961
1962 def violations(registry, xml_parent, data):
1963 """yaml: violations
1964 Publish code style violations.
1965 Requires the Jenkins :jenkins-plugins:`Violations Plugin <violations>`.
1966
1967 The violations component accepts any number of dictionaries keyed
1968 by the name of the violations system. The dictionary has the
1969 following values:
1970
1971 :arg int min: sunny threshold
1972 :arg int max: stormy threshold
1973 :arg int unstable: unstable threshold
1974 :arg str pattern: report filename pattern
1975
1976 Any system without a dictionary provided will use default values.
1977
1978 Valid systems are:
1979
1980 checkstyle, codenarc, cpd, cpplint, csslint, findbugs, fxcop,
1981 gendarme, jcreport, jslint, pep8, perlcritic, pmd, pylint,
1982 simian, stylecop
1983
1984 Example:
1985
1986 .. literalinclude:: /../../tests/publishers/fixtures/violations001.yaml
1987 :language: yaml
1988 """
1989 violations = XML.SubElement(
1990 xml_parent, "hudson.plugins.violations." "ViolationsPublisher"
1991 )
1992 config = XML.SubElement(violations, "config")
1993 suppressions = XML.SubElement(config, "suppressions", {"class": "tree-set"})
1994 XML.SubElement(suppressions, "no-comparator")
1995 configs = XML.SubElement(config, "typeConfigs")
1996 XML.SubElement(configs, "no-comparator")
1997
1998 for name in [
1999 "checkstyle",
2000 "codenarc",
2001 "cpd",
2002 "cpplint",
2003 "csslint",
2004 "findbugs",
2005 "fxcop",
2006 "gendarme",
2007 "jcreport",
2008 "jslint",
2009 "pep8",
2010 "perlcritic",
2011 "pmd",
2012 "pylint",
2013 "simian",
2014 "stylecop",
2015 ]:
2016 _violations_add_entry(configs, name, data.get(name, {}))
2017 mapping = [
2018 ("", "limit", "100"),
2019 ("", "sourcePathPattern", ""),
2020 ("", "fauxProjectPath", ""),
2021 ("", "encoding", "default"),
2022 ]
2023 helpers.convert_mapping_to_xml(config, data, mapping, fail_required=True)
2024
2025
2026 def findbugs(registry, xml_parent, data):
2027 r"""yaml: findbugs
2028 FindBugs reporting for builds
2029
2030 Requires the Jenkins FindBugs Plugin
2031 (:jenkins-github:`findbugs-plugin`).
2032
2033 :arg str pattern: specifies the generated raw FindBugs XML report files,
2034 such as \*\*/findbugs.xml or \*\*/findbugsXml.xml. (default '')
2035 :arg bool rank-priority: Use rank as priority (default false)
2036 :arg str include-files: Comma separated list of files to include.
2037 (default '')
2038 :arg str exclude-files: Comma separated list of files to exclude.
2039 (default '')
2040 :arg bool can-run-on-failed: Weather or not to run plug-in on failed builds
2041 (default false)
2042 :arg bool should-detect-modules: Determines if Ant or Maven modules should
2043 be detected for all files that contain warnings. (default false)
2044 :arg int healthy: Sunny threshold (default '')
2045 :arg int unhealthy: Stormy threshold (default '')
2046 :arg str health-threshold: Threshold priority for health status
2047 ('low', 'normal' or 'high', defaulted to 'low')
2048 :arg bool dont-compute-new: If set to false, computes new warnings based on
2049 the reference build (default true)
2050 :arg bool use-delta-values: Use delta for new warnings. (default false)
2051 :arg bool use-previous-build-as-reference: If set then the number of new
2052 warnings will always be calculated based on the previous build.
2053 Otherwise the reference build. (default false)
2054 :arg bool use-stable-build-as-reference: The number of new warnings will be
2055 calculated based on the last stable build, allowing reverts of unstable
2056 builds where the number of warnings was decreased. (default false)
2057 :arg dict thresholds:
2058 :thresholds:
2059 * **unstable** (`dict`)
2060 :unstable: * **total-all** (`int`)
2061 * **total-high** (`int`)
2062 * **total-normal** (`int`)
2063 * **total-low** (`int`)
2064 * **new-all** (`int`)
2065 * **new-high** (`int`)
2066 * **new-normal** (`int`)
2067 * **new-low** (`int`)
2068
2069 * **failed** (`dict`)
2070 :failed: * **total-all** (`int`)
2071 * **total-high** (`int`)
2072 * **total-normal** (`int`)
2073 * **total-low** (`int`)
2074 * **new-all** (`int`)
2075 * **new-high** (`int`)
2076 * **new-normal** (`int`)
2077 * **new-low** (`int`)
2078
2079 Minimal Example:
2080
2081 .. literalinclude:: /../../tests/publishers/fixtures/findbugs-minimal.yaml
2082
2083 Full Example:
2084
2085 .. literalinclude:: /../../tests/publishers/fixtures/findbugs-full.yaml
2086 """
2087 findbugs = XML.SubElement(xml_parent, "hudson.plugins.findbugs.FindBugsPublisher")
2088 findbugs.set("plugin", "findbugs")
2089
2090 helpers.findbugs_settings(findbugs, data)
2091 helpers.build_trends_publisher("[FINDBUGS] ", findbugs, data)
2092
2093
2094 def checkstyle(registry, xml_parent, data):
2095 """yaml: checkstyle
2096 Publish trend reports with Checkstyle.
2097
2098 Requires the Jenkins Checkstyle Plugin
2099 (:jenkins-github:`checkstyle-plugin`).
2100
2101 The checkstyle component accepts a dictionary with the
2102 following values:
2103
2104 :arg str pattern: Report filename pattern (default '')
2105 :arg bool can-run-on-failed: Also runs for failed builds, instead of just
2106 stable or unstable builds (default false)
2107 :arg bool should-detect-modules: Determines if Ant or Maven modules should
2108 be detected for all files that contain warnings (default false)
2109 :arg int healthy: Sunny threshold (default '')
2110 :arg int unhealthy: Stormy threshold (default '')
2111 :arg str health-threshold: Threshold priority for health status
2112 ('low', 'normal' or 'high') (default 'low')
2113 :arg dict thresholds: Mark build as failed or unstable if the number of
2114 errors exceeds a threshold. (optional)
2115
2116 :thresholds:
2117 * **unstable** (`dict`)
2118 :unstable: * **total-all** (`int`)
2119 * **total-high** (`int`)
2120 * **total-normal** (`int`)
2121 * **total-low** (`int`)
2122 * **new-all** (`int`)
2123 * **new-high** (`int`)
2124 * **new-normal** (`int`)
2125 * **new-low** (`int`)
2126
2127 * **failed** (`dict`)
2128 :failed: * **total-all** (`int`)
2129 * **total-high** (`int`)
2130 * **total-normal** (`int`)
2131 * **total-low** (`int`)
2132 * **new-all** (`int`)
2133 * **new-high** (`int`)
2134 * **new-normal** (`int`)
2135 * **new-low** (`int`)
2136 :arg str default-encoding: Encoding for parsing or showing files
2137 (default '')
2138 :arg bool do-not-resolve-relative-paths: (default false)
2139 :arg bool dont-compute-new: If set to false, computes new warnings based on
2140 the reference build (default true)
2141 :arg bool use-previous-build-as-reference: determines whether to always
2142 use the previous build as the reference build (default false)
2143 :arg bool use-stable-build-as-reference: The number of new warnings will be
2144 calculated based on the last stable build, allowing reverts of unstable
2145 builds where the number of warnings was decreased. (default false)
2146 :arg bool use-delta-values: If set then the number of new warnings is
2147 calculated by subtracting the total number of warnings of the current
2148 build from the reference build. (default false)
2149
2150 Example:
2151
2152 .. literalinclude:: /../../tests/publishers/fixtures/checkstyle004.yaml
2153 :language: yaml
2154
2155 Full example:
2156
2157 .. literalinclude:: /../../tests/publishers/fixtures/checkstyle006.yaml
2158 :language: yaml
2159 """
2160
2161 def convert_settings(lookup, data):
2162 """Helper to convert settings from one key to another."""
2163
2164 for old_key in list(data.keys()):
2165 if old_key in lookup:
2166 data.setdefault(lookup[old_key], data[old_key])
2167 del data[old_key]
2168
2169 checkstyle = XML.SubElement(
2170 xml_parent, "hudson.plugins.checkstyle." "CheckStylePublisher"
2171 )
2172 checkstyle.set("plugin", "checkstyle")
2173
2174 # Convert old style yaml to new style
2175 convert_settings(
2176 {
2177 "unHealthy": "unhealthy",
2178 "healthThreshold": "health-threshold",
2179 "defaultEncoding": "default-encoding",
2180 "canRunOnFailed": "can-run-on-failed",
2181 "shouldDetectModules": "should-detect-modules",
2182 },
2183 data,
2184 )
2185
2186 threshold_data = data.get("thresholds", {})
2187 for threshold in ["unstable", "failed"]:
2188 convert_settings(
2189 {
2190 "totalAll": "total-all",
2191 "totalHigh": "total-high",
2192 "totalNormal": "total-normal",
2193 "totalLow": "total-low",
2194 },
2195 threshold_data.get(threshold, {}),
2196 )
2197
2198 helpers.build_trends_publisher("[CHECKSTYLE] ", checkstyle, data)
2199
2200
2201 def scp(registry, xml_parent, data):
2202 """yaml: scp
2203 Upload files via SCP
2204 Requires the Jenkins :jenkins-plugins:`SCP Plugin <scp>`.
2205
2206 When writing a publisher macro, it is important to keep in mind that
2207 Jenkins uses Ant's `SCP Task
2208 <https://ant.apache.org/manual/Tasks/scp.html>`_ via the Jenkins
2209 :jenkins-plugins:`SCP Plugin <scp>` which relies on `FileSet
2210 <https://ant.apache.org/manual/Types/fileset.html>`_
2211 and `DirSet <https://ant.apache.org/manual/Types/dirset.html>`_ patterns.
2212 The relevant piece of documentation is excerpted below:
2213
2214 Source points to files which will be uploaded. You can use ant
2215 includes syntax, eg. ``folder/dist/*.jar``. Path is constructed from
2216 workspace root. Note that you cannot point files outside the workspace
2217 directory. For example providing: ``../myfile.txt`` won't work...
2218 Destination points to destination folder on remote site. It will be
2219 created if doesn't exists and relative to root repository path. You
2220 can define multiple blocks of source/destination pairs.
2221
2222 This means that absolute paths, e.g., ``/var/log/**`` will not work and
2223 will fail to compile. All paths need to be relative to the directory that
2224 the publisher runs and the paths have to be contained inside of that
2225 directory. The relative working directory is usually::
2226
2227 /home/jenkins/workspace/${JOB_NAME}
2228
2229 :arg str site: name of the scp site (required)
2230 :arg str target: destination directory (required)
2231 :arg str source: source path specifier (default '')
2232 :arg bool keep-hierarchy: keep the file hierarchy when uploading
2233 (default false)
2234 :arg bool copy-after-failure: copy files even if the job fails
2235 (default false)
2236 :arg bool copy-console: copy the console log (default false); if
2237 specified, omit 'source'
2238
2239 Example:
2240
2241 .. literalinclude:: /../../tests/publishers/fixtures/scp001.yaml
2242 :language: yaml
2243 """
2244 scp = XML.SubElement(
2245 xml_parent, "be.certipost.hudson.plugin.SCPRepositoryPublisher"
2246 )
2247 scp.set("plugin", "scp")
2248
2249 mappings = [("site", "siteName", None)]
2250 helpers.convert_mapping_to_xml(scp, data, mappings, fail_required=True)
2251
2252 entries = XML.SubElement(scp, "entries")
2253 for entry in data["files"]:
2254 entry_e = XML.SubElement(entries, "be.certipost.hudson.plugin.Entry")
2255 mappings = [
2256 ("target", "filePath", None),
2257 ("source", "sourceFile", ""),
2258 ("keep-hierarchy", "keepHierarchy", False),
2259 ("copy-console", "copyConsoleLog", False),
2260 ("copy-after-failure", "copyAfterFailure", False),
2261 ]
2262 helpers.convert_mapping_to_xml(entry_e, entry, mappings, fail_required=True)
2263
2264
2265 def ssh(registry, xml_parent, data):
2266 """yaml: ssh
2267 Upload files via SCP.
2268 Requires the Jenkins :jenkins-plugins:`Publish over SSH Plugin
2269 <publish-over-ssh>`.
2270
2271 :arg str site: name of the ssh site
2272 :arg str target: destination directory
2273 :arg bool target-is-date-format: whether target is a date format. If true,
2274 raw text should be quoted (default false)
2275 :arg bool clean-remote: should the remote directory be deleted before
2276 transferring files (default false)
2277 :arg str source: source path specifier
2278 :arg str command: a command to execute on the remote server (optional)
2279 :arg int timeout: timeout in milliseconds for the Exec command (optional)
2280 :arg bool use-pty: run the exec command in pseudo TTY (default false)
2281 :arg str excludes: excluded file pattern (optional)
2282 :arg str remove-prefix: prefix to remove from uploaded file paths
2283 (optional)
2284 :arg bool fail-on-error: fail the build if an error occurs (default false).
2285 :arg bool always-publish-from-master: transfer the files through the master
2286 before being sent to the remote server (defaults false)
2287 :arg bool flatten: only create files on the server, don't create
2288 directories (default false).
2289 :arg bool verbose: adds lots of detail useful for debug to the console
2290 but generally should be left off (default false)
2291 :arg int retries: the number of times to retry this server in the event of
2292 failure (optional)
2293 :arg int retry-delay: the time to wait, in milliseconds, before attempting
2294 another transfer (default 10000)
2295
2296 Minimal Example:
2297
2298 .. literalinclude:: /../../tests/publishers/fixtures/ssh-minimal.yaml
2299 :language: yaml
2300
2301 Full Example:
2302
2303 .. literalinclude:: /../../tests/publishers/fixtures/ssh-full.yaml
2304 :language: yaml
2305 """
2306 console_prefix = "SSH: "
2307 tag_prefix = "jenkins.plugins.publish"
2308 publisher_tag = "%s__over__ssh.BapSshPublisher" % tag_prefix
2309 transfer_tag = "%s__over__ssh.BapSshTransfer" % tag_prefix
2310 retry_tag = "%s_over_ssh.BapSshRetry" % tag_prefix
2311 reference_tag = "%s_over_ssh.BapSshPublisherPlugin" % tag_prefix
2312
2313 if xml_parent.tag == "publishers":
2314 plugin_tag = "%s__over__ssh.BapSshPublisherPlugin" % tag_prefix
2315 is_builder = False
2316 else:
2317 plugin_tag = "%s__over__ssh.BapSshBuilderPlugin" % tag_prefix
2318 is_builder = True
2319
2320 base_publish_over(
2321 xml_parent,
2322 data,
2323 console_prefix,
2324 plugin_tag,
2325 publisher_tag,
2326 transfer_tag,
2327 retry_tag,
2328 reference_tag,
2329 is_builder,
2330 )
2331
2332
2333 def pipeline(registry, xml_parent, data):
2334 """yaml: pipeline
2335 Specify a downstream project in a pipeline.
2336 Requires the Jenkins :jenkins-plugins:`Build Pipeline Plugin
2337 <build-pipeline-plugin>`.
2338
2339 Use of the `node-label-name` or `node-label` parameters
2340 requires the Jenkins :jenkins-plugins:`NodeLabel Parameter Plugin
2341 <nodelabelparameter>`.
2342 Note: 'node-parameters' overrides the Node that the triggered
2343 project is tied to.
2344
2345 :arg list projects: list the jobs to trigger, will generate comma-separated
2346 string containing the named jobs.
2347 :arg str predefined-parameters: parameters to pass to the other
2348 job (optional)
2349 :arg bool current-parameters: Whether to include the parameters passed
2350 to the current build to the triggered job (optional)
2351 :arg bool node-parameters: Use the same Node for the triggered builds
2352 that was used for this build. (optional)
2353 :arg bool svn-revision: Pass svn revision to the triggered job (optional)
2354 :arg bool include-upstream: Include/pass through Upstream SVN Revisons.
2355 Only valid when 'svn-revision' is true. (default false)
2356 :arg dict git-revision: Passes git revision to the triggered job
2357 (optional).
2358
2359 * **combine-queued-commits** (bool): Whether to combine queued git
2360 hashes or not (default false)
2361
2362 :arg dict boolean-parameters: Pass boolean parameters to the downstream
2363 jobs. Specify the name and boolean value mapping of the parameters.
2364 (optional)
2365 :arg str property-file: Use properties from file (optional)
2366 :arg bool fail-on-missing: Blocks the triggering of the downstream jobs
2367 if any of the property files are not found in the workspace.
2368 Only valid when 'property-file' is specified.
2369 (default false)
2370 :arg str file-encoding: Encoding of contents of the files. If not
2371 specified, default encoding of the platform is used. Only valid when
2372 'property-file' is specified. (optional)
2373 :arg str restrict-matrix-project: Filter that restricts the subset
2374 of the combinations that the downstream project will run (optional)
2375
2376 Example:
2377
2378 .. literalinclude:: /../../tests/publishers/fixtures/pipeline002.yaml
2379 :language: yaml
2380
2381 .. literalinclude:: /../../tests/publishers/fixtures/pipeline003.yaml
2382 :language: yaml
2383
2384
2385 You can build pipeline jobs that are re-usable in different pipelines by
2386 using a :ref:`job-template` to define the pipeline jobs,
2387 and variable substitution to specify the name of
2388 the downstream job in the pipeline.
2389 Job-specific substitutions are useful here (see :ref:`project`).
2390
2391 See 'samples/pipeline.yaml' for an example pipeline implementation.
2392 """
2393 logger = logging.getLogger("%s:pipeline" % __name__)
2394 param_order = helpers.trigger_get_parameter_order(registry, "pipeline")
2395
2396 if "project" in data:
2397 logger.warning(
2398 "Using 'project' for pipeline definition is deprecated. Please "
2399 "update your job definition to use 'projects' with a list format."
2400 )
2401
2402 projects = ",".join(data.get("projects", [data.get("project", "")]))
2403 if projects != "":
2404
2405 pippub = XML.SubElement(
2406 xml_parent,
2407 "au.com.centrumsystems.hudson.plugin."
2408 "buildpipeline.trigger.BuildPipelineTrigger",
2409 )
2410
2411 configs = XML.SubElement(pippub, "configs")
2412
2413 helpers.trigger_project(configs, data, registry, param_order)
2414
2415 XML.SubElement(pippub, "downstreamProjectNames").text = projects
2416
2417
2418 def email(registry, xml_parent, data):
2419 """yaml: email
2420 Email notifications on build failure.
2421 Requires the Jenkins :jenkins-plugins:`Mailer Plugin <mailer>`.
2422
2423 :arg str recipients: Space separated list of recipient email addresses
2424 (required)
2425 :arg bool notify-every-unstable-build: Send an email for every
2426 unstable build (default true)
2427 :arg bool send-to-individuals: Send an email to the individual
2428 who broke the build (default false)
2429
2430 Example:
2431
2432 .. literalinclude::
2433 /../../tests/publishers/fixtures/email-minimal.yaml
2434 :language: yaml
2435
2436 .. literalinclude:: /../../tests/publishers/fixtures/email-full.yaml
2437 :language: yaml
2438 """
2439
2440 # TODO: raise exception if this is applied to a maven job
2441 mailer = XML.SubElement(xml_parent, "hudson.tasks.Mailer")
2442 mailer.set("plugin", "mailer")
2443 mapping = [("recipients", "recipients", None)]
2444 helpers.convert_mapping_to_xml(mailer, data, mapping, fail_required=True)
2445
2446 # Note the logic reversal (included here to match the GUI
2447 if data.get("notify-every-unstable-build", True):
2448 XML.SubElement(mailer, "dontNotifyEveryUnstableBuild").text = "false"
2449 else:
2450 XML.SubElement(mailer, "dontNotifyEveryUnstableBuild").text = "true"
2451 XML.SubElement(mailer, "sendToIndividuals").text = str(
2452 data.get("send-to-individuals", False)
2453 ).lower()
2454
2455
2456 def claim_build(registry, xml_parent, data):
2457 """yaml: claim-build
2458 Claim build failures
2459 Requires the Jenkins :jenkins-plugins:`Claim Plugin <claim>`.
2460
2461 Example:
2462
2463 .. literalinclude:: /../../tests/publishers/fixtures/claim-build001.yaml
2464 :language: yaml
2465 """
2466
2467 XML.SubElement(xml_parent, "hudson.plugins.claim.ClaimPublisher")
2468
2469
2470 def base_email_ext(registry, xml_parent, data, ttype):
2471 trigger = XML.SubElement(
2472 xml_parent, "hudson.plugins.emailext.plugins.trigger." + ttype
2473 )
2474
2475 plugin_ver = registry.get_plugin_version("email-ext")
2476
2477 email = XML.SubElement(trigger, "email")
2478
2479 if plugin_ver < "2.39":
2480 XML.SubElement(email, "recipientList").text = ""
2481 XML.SubElement(email, "subject").text = "$PROJECT_DEFAULT_SUBJECT"
2482 XML.SubElement(email, "body").text = "$PROJECT_DEFAULT_CONTENT"
2483 if plugin_ver >= "2.39":
2484 XML.SubElement(email, "replyTo").text = "$PROJECT_DEFAULT_REPLYTO"
2485 XML.SubElement(email, "contentType").text = "project"
2486 if "send-to" in data:
2487 recipient_providers = None
2488 if plugin_ver < "2.39":
2489 XML.SubElement(email, "sendToDevelopers").text = str(
2490 "developers" in data["send-to"]
2491 ).lower()
2492 XML.SubElement(email, "sendToRequester").text = str(
2493 "requester" in data["send-to"]
2494 ).lower()
2495 XML.SubElement(email, "includeCulprits").text = str(
2496 "culprits" in data["send-to"]
2497 ).lower()
2498 XML.SubElement(email, "sendToRecipientList").text = str(
2499 "recipients" in data["send-to"]
2500 ).lower()
2501 else:
2502 for recipient in data["send-to"]:
2503 if "developers" == recipient:
2504 if recipient_providers is None:
2505 recipient_providers = XML.SubElement(
2506 email, "recipientProviders"
2507 )
2508 XML.SubElement(
2509 recipient_providers,
2510 "hudson.plugins.emailext.plugins.recipients.DevelopersRecipientProvider",
2511 ).text = ""
2512 elif "requester" == recipient:
2513 if recipient_providers is None:
2514 recipient_providers = XML.SubElement(
2515 email, "recipientProviders"
2516 )
2517 XML.SubElement(
2518 recipient_providers,
2519 "hudson.plugins.emailext.plugins.recipients.RequesterRecipientProvider",
2520 ).text = ""
2521 elif "culprits" == recipient:
2522 if recipient_providers is None:
2523 recipient_providers = XML.SubElement(
2524 email, "recipientProviders"
2525 )
2526 XML.SubElement(
2527 recipient_providers,
2528 "hudson.plugins.emailext.plugins.recipients.CulpritsRecipientProvider",
2529 ).text = ""
2530 elif "recipients" == recipient:
2531 if recipient_providers is None:
2532 recipient_providers = XML.SubElement(
2533 email, "recipientProviders"
2534 )
2535 XML.SubElement(
2536 recipient_providers,
2537 "hudson.plugins.emailext.plugins.recipients.ListRecipientProvider",
2538 ).text = ""
2539 elif "failing-test-suspects-recipients" == recipient:
2540 if recipient_providers is None:
2541 recipient_providers = XML.SubElement(
2542 email, "recipientProviders"
2543 )
2544 XML.SubElement(
2545 recipient_providers,
2546 "hudson.plugins.emailext.plugins.recipients.FailingTestSuspectsRecipientProvider",
2547 ).text = ""
2548 elif "first-failing-build-suspects-recipients" == recipient:
2549 if recipient_providers is None:
2550 recipient_providers = XML.SubElement(
2551 email, "recipientProviders"
2552 )
2553 XML.SubElement(
2554 recipient_providers,
2555 "hudson.plugins.emailext.plugins.recipients.FirstFailingBuildSuspectsRecipientProvider",
2556 ).text = ""
2557 # `failureCount` is deprecated and has no effect
2558 # on email, but the element has been created
2559 # in order to match the XML generated via UI.
2560 failure_count_supporters = ["FirstFailureTrigger", "SecondFailureTrigger"]
2561 if ttype in failure_count_supporters:
2562 XML.SubElement(trigger, "failureCount").text = "0"
2563 if "upstream-committers" in data["send-to"]:
2564 if recipient_providers is None:
2565 recipient_providers = XML.SubElement(email, "recipientProviders")
2566 XML.SubElement(
2567 recipient_providers,
2568 "hudson.plugins.emailext.plugins.recipients.UpstreamComitterRecipientProvider",
2569 ).text = ""
2570 else:
2571 if plugin_ver < "2.39":
2572 XML.SubElement(email, "sendToRequester").text = "false"
2573 XML.SubElement(email, "sendToDevelopers").text = "false"
2574 XML.SubElement(email, "includeCulprits").text = "false"
2575 XML.SubElement(email, "sendToRecipientList").text = "true"
2576 else:
2577 recipient_providers = XML.SubElement(email, "recipientProviders")
2578 XML.SubElement(
2579 recipient_providers,
2580 "hudson.plugins.emailext.plugins.recipients.ListRecipientProvider",
2581 ).text = ""
2582
2583 if ttype == "ScriptTrigger":
2584 XML.SubElement(trigger, "triggerScript").text = data["trigger-script"]
2585
2586 if plugin_ver >= "2.39":
2587 mappings = [
2588 ("attachments", "attachmentsPattern", ""),
2589 ("attach-build-log", "attachBuildLog", False),
2590 ("compress-log", "compressBuildLog", False),
2591 ]
2592
2593 helpers.convert_mapping_to_xml(email, data, mappings, fail_required=True)
2594
2595
2596 def email_ext(registry, xml_parent, data):
2597 """yaml: email-ext
2598 Extend Jenkin's built in email notification
2599 Requires the Jenkins :jenkins-plugins:`Email-ext Plugin
2600 <email-ext>`.
2601
2602 :arg bool disable-publisher: Disable the publisher, while maintaining the
2603 settings. The usage model for this is when you want to test things out
2604 in the build, not send out e-mails during the testing. A message will
2605 be printed to the build log saying that the publisher is disabled.
2606 (default false)
2607 :arg str recipients: Comma separated list of recipient email addresses
2608 (default '$DEFAULT_RECIPIENTS')
2609 :arg str reply-to: Comma separated list of email addresses that should be
2610 in the Reply-To header for this project (default '$DEFAULT_REPLYTO')
2611 :arg str from: Email address that should be
2612 in the From header for this project (default '')
2613 :arg str content-type: The content type of the emails sent. If not set, the
2614 Jenkins plugin uses the value set on the main configuration page.
2615 Possible values: 'html', 'text', 'both-html-text' or 'default'
2616 (default 'default')
2617 :arg str subject: Subject for the email, can include variables like
2618 ${BUILD_NUMBER} or even groovy or javascript code
2619 (default '$DEFAULT_SUBJECT')
2620 :arg str body: Content for the body of the email, can include variables
2621 like ${BUILD_NUMBER}, but the real magic is using groovy or
2622 javascript to hook into the Jenkins API itself
2623 (default '$DEFAULT_CONTENT')
2624 :arg bool attach-build-log: Include build log in the email (default false)
2625 :arg bool compress-log: Compress build log in the email (default false)
2626 :arg str attachments: pattern of files to include as attachment
2627 (default '')
2628 :arg bool always: Send an email for every result (default false)
2629 :arg bool unstable: Send an email for an unstable result (default false)
2630 :arg bool first-failure: Send an email for just the first failure
2631 (default false)
2632 :arg bool first-unstable: Send an email for just the first unstable build
2633 (default false)
2634 :arg bool not-built: Send an email if not built (default false)
2635 :arg bool aborted: Send an email if the build is aborted (default false)
2636 :arg bool regression: Send an email if there is a regression
2637 (default false)
2638 :arg bool failure: Send an email if the build fails (default true)
2639 :arg bool second-failure: Send an email for the second failure
2640 (default false)
2641 :arg bool improvement: Send an email if the build improves (default false)
2642 :arg bool still-failing: Send an email if the build is still failing
2643 (default false)
2644 :arg bool success: Send an email for a successful build (default false)
2645 :arg bool fixed: Send an email if the build is fixed (default false)
2646 :arg bool fixed-unhealthy: Send an email if the build status
2647 changes from "Failure" or "Unstable" to "Success". Intermediate
2648 "Aborted" builds are ignored. (default false)
2649 :arg bool still-unstable: Send an email if the build is still unstable
2650 (default false)
2651 :arg bool pre-build: Send an email before the build (default false)
2652 :arg str trigger-script: A Groovy script used to determine if an email
2653 should be sent.
2654 :arg str presend-script: A Groovy script executed prior sending the mail.
2655 (default '')
2656 :arg str postsend-script: A Goovy script executed after sending the email.
2657 (default '')
2658 :arg bool save-output: Save email content to workspace (default false)
2659 :arg str matrix-trigger: If using matrix projects, when to trigger
2660
2661 :matrix-trigger values:
2662 * **both**
2663 * **only-parent**
2664 * **only-configurations**
2665 :arg list send-to: list of recipients from the predefined groups
2666
2667 :send-to values:
2668 * **developers** (disabled by default)
2669 * **requester** (disabled by default)
2670 * **culprits** (disabled by default)
2671 * **recipients** (enabled by default)
2672 * **upstream-committers** (>=2.39) (disabled by default)
2673 * **failing-test-suspects-recipients** (>=2.39) (disabled by default)
2674 * **first-failing-build-suspects-recipients** (>=2.39) (disabled by default)
2675
2676 Example:
2677
2678 .. literalinclude:: /../../tests/publishers/fixtures/email-ext001.yaml
2679 :language: yaml
2680 """
2681
2682 emailext = XML.SubElement(
2683 xml_parent, "hudson.plugins.emailext.ExtendedEmailPublisher"
2684 )
2685
2686 plugin_ver = registry.get_plugin_version("email-ext")
2687
2688 if "recipients" in data:
2689 XML.SubElement(emailext, "recipientList").text = data["recipients"]
2690 else:
2691 XML.SubElement(emailext, "recipientList").text = "$DEFAULT_RECIPIENTS"
2692 ctrigger = XML.SubElement(emailext, "configuredTriggers")
2693 if data.get("always", False):
2694 base_email_ext(registry, ctrigger, data, "AlwaysTrigger")
2695 if data.get("unstable", False):
2696 base_email_ext(registry, ctrigger, data, "UnstableTrigger")
2697 if data.get("first-failure", False):
2698 base_email_ext(registry, ctrigger, data, "FirstFailureTrigger")
2699 if data.get("first-unstable", False):
2700 base_email_ext(registry, ctrigger, data, "FirstUnstableTrigger")
2701 if data.get("not-built", False):
2702 base_email_ext(registry, ctrigger, data, "NotBuiltTrigger")
2703 if data.get("aborted", False):
2704 base_email_ext(registry, ctrigger, data, "AbortedTrigger")
2705 if data.get("regression", False):
2706 base_email_ext(registry, ctrigger, data, "RegressionTrigger")
2707 if data.get("failure", True):
2708 base_email_ext(registry, ctrigger, data, "FailureTrigger")
2709 if data.get("second-failure", False):
2710 base_email_ext(registry, ctrigger, data, "SecondFailureTrigger")
2711 if data.get("improvement", False):
2712 base_email_ext(registry, ctrigger, data, "ImprovementTrigger")
2713 if data.get("still-failing", False):
2714 base_email_ext(registry, ctrigger, data, "StillFailingTrigger")
2715 if data.get("success", False):
2716 base_email_ext(registry, ctrigger, data, "SuccessTrigger")
2717 if data.get("fixed", False):
2718 base_email_ext(registry, ctrigger, data, "FixedTrigger")
2719 if data.get("fixed-unhealthy", False):
2720 base_email_ext(registry, ctrigger, data, "FixedUnhealthyTrigger")
2721 if data.get("still-unstable", False):
2722 base_email_ext(registry, ctrigger, data, "StillUnstableTrigger")
2723 if data.get("pre-build", False):
2724 base_email_ext(registry, ctrigger, data, "PreBuildTrigger")
2725 if data.get("trigger-script", False):
2726 base_email_ext(registry, ctrigger, data, "ScriptTrigger")
2727
2728 content_type_mime = {
2729 "text": "text/plain",
2730 "html": "text/html",
2731 "default": "default",
2732 "both-html-text": "both",
2733 }
2734 ctype = data.get("content-type", "default")
2735 if ctype not in content_type_mime:
2736 raise InvalidAttributeError(ctype, ctype, content_type_mime.keys())
2737 XML.SubElement(emailext, "contentType").text = content_type_mime[ctype]
2738
2739 mappings = [
2740 ("subject", "defaultSubject", "$DEFAULT_SUBJECT"),
2741 ("body", "defaultContent", "$DEFAULT_CONTENT"),
2742 ("attachments", "attachmentsPattern", ""),
2743 ("presend-script", "presendScript", ""),
2744 ("postsend-script", "postsendScript", ""),
2745 ("attach-build-log", "attachBuildLog", False),
2746 ("compress-log", "compressBuildLog", False),
2747 ("save-output", "saveOutput", False),
2748 ("disable-publisher", "disabled", False),
2749 ("reply-to", "replyTo", "$DEFAULT_REPLYTO"),
2750 ]
2751
2752 if plugin_ver >= "2.39":
2753 mappings.append(("from", "from", ""))
2754
2755 helpers.convert_mapping_to_xml(emailext, data, mappings, fail_required=True)
2756
2757 matrix_dict = {
2758 "both": "BOTH",
2759 "only-configurations": "ONLY_CONFIGURATIONS",
2760 "only-parent": "ONLY_PARENT",
2761 }
2762 matrix_trigger = data.get("matrix-trigger", None)
2763 # If none defined, then do not create entry
2764 if matrix_trigger is not None:
2765 if matrix_trigger not in matrix_dict:
2766 raise InvalidAttributeError(
2767 matrix_trigger, matrix_trigger, matrix_dict.keys()
2768 )
2769 XML.SubElement(emailext, "matrixTriggerMode").text = matrix_dict.get(
2770 matrix_trigger
2771 )
2772
2773
2774 def fingerprint(registry, xml_parent, data):
2775 """yaml: fingerprint
2776 Fingerprint files to track them across builds. Requires the
2777 Jenkins :jenkins-plugins:`Fingerprint Plugin <create-fingerprint>`.
2778
2779 :arg str files: files to fingerprint, follows the @includes of Ant fileset
2780 (default '')
2781 :arg bool record-artifacts: fingerprint all archived artifacts
2782 (default false)
2783
2784 Example:
2785
2786 .. literalinclude:: /../../tests/publishers/fixtures/fingerprint001.yaml
2787 :language: yaml
2788 """
2789 finger = XML.SubElement(xml_parent, "hudson.tasks.Fingerprinter")
2790 mappings = [
2791 ("files", "targets", ""),
2792 ("record-artifacts", "recordBuildArtifacts", False),
2793 ]
2794 helpers.convert_mapping_to_xml(finger, data, mappings, fail_required=True)
2795
2796
2797 def aggregate_tests(registry, xml_parent, data):
2798 """yaml: aggregate-tests
2799 Aggregate downstream test results
2800
2801 :arg bool include-failed-builds: whether to include failed builds
2802 (default false)
2803
2804 Example:
2805
2806 .. literalinclude::
2807 /../../tests/publishers/fixtures/aggregate-tests001.yaml
2808 :language: yaml
2809 """
2810 agg = XML.SubElement(xml_parent, "hudson.tasks.test.AggregatedTestResultPublisher")
2811 mapping = [("include-failed-builds", "includeFailedBuilds", False)]
2812 helpers.convert_mapping_to_xml(agg, data, mapping, fail_required=True)
2813
2814
2815 def aggregate_flow_tests(registry, xml_parent, data):
2816 """yaml: aggregate-flow-tests
2817 Aggregate downstream test results in a Build Flow job.
2818
2819 Requires the Jenkins `Build Flow Test Aggregator Plugin
2820 <https://github.com/zeroturnaround/build-flow-test-aggregator>`_.
2821
2822 :arg bool show-test-results-trend: whether to show test results
2823 trend graph (default true)
2824
2825 Example:
2826
2827 .. literalinclude::
2828 /../../tests/publishers/fixtures/aggregate-flow-tests002.yaml
2829 :language: yaml
2830
2831 """
2832 agg_flow = XML.SubElement(
2833 xml_parent,
2834 "org.zeroturnaround.jenkins." "flowbuildtestaggregator.FlowTestAggregator",
2835 )
2836 mapping = [("show-test-results-trend", "showTestResultTrend", True)]
2837 helpers.convert_mapping_to_xml(agg_flow, data, mapping, fail_required=True)
2838
2839
2840 def cppcheck(registry, xml_parent, data):
2841 """yaml: cppcheck
2842 Cppcheck result publisher
2843 Requires the Jenkins :jenkins-plugins:`Cppcheck Plugin <cppcheck>`.
2844
2845 :arg str pattern: File pattern for cppcheck xml report (required)
2846 :arg bool ignoreblankfiles: Ignore blank files (default false)
2847 :arg bool allow-no-report: Do not fail the build if the Cppcheck report
2848 is not found (default false)
2849 :arg dict thresholds:
2850 :thresholds: Configure the build status and health. A build is
2851 considered as unstable or failure if the new or total number
2852 of issues exceeds the specified thresholds. The build health
2853 is also determined by thresholds. If the actual number of issues
2854 is between the provided thresholds, then the build health is
2855 interpolated.
2856
2857 * **unstable** (`str`): Total number unstable threshold (default '')
2858 * **new-unstable** (`str`): New number unstable threshold (default '')
2859 * **failure** (`str`): Total number failure threshold (default '')
2860 * **new-failure** (`str`): New number failure threshold (default '')
2861 * **healthy** (`str`): Healthy threshold (default '')
2862 * **unhealthy** (`str`): Unhealthy threshold (default '')
2863
2864 :arg dict severity:
2865 :severity: Determines which severity of issues should be considered
2866 when evaluating the build status and health, default all true
2867
2868 * **error** (`bool`): Severity error (default true)
2869 * **warning** (`bool`): Severity warning (default true)
2870 * **style** (`bool`): Severity style (default true)
2871 * **performance** (`bool`): Severity performance (default true)
2872 * **information** (`bool`): Severity information (default true)
2873 * **nocategory** (`bool`): Severity nocategory (default true)
2874 * **portability** (`bool`): Severity portability (default true)
2875
2876 :arg dict graph:
2877 :graph: Graph configuration
2878
2879 * **xysize** (`array`): Chart width and height (default [500, 200])
2880 * **num-builds-in-graph** (`int`): Builds number in graph (default 0)
2881
2882 :arg dict display
2883 :display: which errors to display, default only sum
2884
2885 * **sum** (`bool`): Display sum of all issues (default true)
2886 * **error** (`bool`): Display errors (default false)
2887 * **warning** (`bool`): Display warnings (default false)
2888 * **style** (`bool`): Display style (default false)
2889 * **performance** (`bool`): Display performance (default false)
2890 * **information** (`bool`): Display information (default false)
2891 * **nocategory** (`bool`): Display no category (default false)
2892 * **portability** (`bool`): Display portability (default false)
2893
2894 Minimal Example:
2895
2896 .. literalinclude::
2897 /../../tests/publishers/fixtures/cppcheck-minimal.yaml
2898 :language: yaml
2899
2900 Full Example:
2901
2902 .. literalinclude::
2903 /../../tests/publishers/fixtures/cppcheck-full.yaml
2904 :language: yaml
2905 """
2906
2907 cppextbase = XML.SubElement(
2908 xml_parent, "org.jenkinsci.plugins.cppcheck." "CppcheckPublisher"
2909 )
2910 cppextbase.set("plugin", "cppcheck")
2911 cppext = XML.SubElement(cppextbase, "cppcheckConfig")
2912 mappings = [
2913 ("pattern", "pattern", None),
2914 ("ignoreblankfiles", "ignoreBlankFiles", False),
2915 ("allow-no-report", "allowNoReport", False),
2916 ]
2917 helpers.convert_mapping_to_xml(cppext, data, mappings, fail_required=True)
2918
2919 csev = XML.SubElement(cppext, "configSeverityEvaluation")
2920 thrsh = data.get("thresholds", {})
2921 thrsh_mappings = [
2922 ("unstable", "threshold", ""),
2923 ("new-unstable", "newThreshold", ""),
2924 ("failure", "failureThreshold", ""),
2925 ("new-failure", "newFailureThreshold", ""),
2926 ("healthy", "healthy", ""),
2927 ("unhealthy", "unHealthy", ""),
2928 ]
2929 helpers.convert_mapping_to_xml(csev, thrsh, thrsh_mappings, fail_required=True)
2930
2931 sev = thrsh.get("severity", {})
2932 sev_mappings = [
2933 ("error", "severityError", True),
2934 ("warning", "severityWarning", True),
2935 ("style", "severityStyle", True),
2936 ("performance", "severityPerformance", True),
2937 ("information", "severityInformation", True),
2938 ("nocategory", "severityNoCategory", True),
2939 ("portability", "severityPortability", True),
2940 ]
2941 helpers.convert_mapping_to_xml(csev, sev, sev_mappings, fail_required=True)
2942
2943 graph = data.get("graph", {})
2944 cgraph = XML.SubElement(cppext, "configGraph")
2945 x, y = graph.get("xysize", [500, 200])
2946 XML.SubElement(cgraph, "xSize").text = str(x)
2947 XML.SubElement(cgraph, "ySize").text = str(y)
2948 graph_mapping = [("num-builds-in-graph", "numBuildsInGraph", 0)]
2949 helpers.convert_mapping_to_xml(cgraph, graph, graph_mapping, fail_required=True)
2950
2951 gdisplay = graph.get("display", {})
2952 gdisplay_mappings = [
2953 ("sum", "displayAllErrors", True),
2954 ("error", "displayErrorSeverity", False),
2955 ("warning", "displayWarningSeverity", False),
2956 ("style", "displayStyleSeverity", False),
2957 ("performance", "displayPerformanceSeverity", False),
2958 ("information", "displayInformationSeverity", False),
2959 ("nocategory", "displayNoCategorySeverity", False),
2960 ("portability", "displayPortabilitySeverity", False),
2961 ]
2962 helpers.convert_mapping_to_xml(
2963 cgraph, gdisplay, gdisplay_mappings, fail_required=True
2964 )
2965
2966
2967 def logparser(registry, xml_parent, data):
2968 """yaml: logparser
2969 Requires the Jenkins :jenkins-plugins:`Log Parser Plugin <log-parser>`.
2970
2971 :arg str parse-rules: full path to parse rules (default '')
2972 :arg bool use-project-rules: use project rules instead of global
2973 (default true)
2974 :arg bool unstable-on-warning: mark build unstable on warning
2975 (default false)
2976 :arg bool fail-on-error: mark build failed on error (default false)
2977 :arg bool show-graphs: show parser trend graphs (default true)
2978
2979 Minimal Example:
2980
2981 .. literalinclude::
2982 /../../tests/publishers/fixtures/logparser-minimal.yaml
2983 :language: yaml
2984
2985 Full Example:
2986
2987 .. literalinclude::
2988 /../../tests/publishers/fixtures/logparser-full.yaml
2989 :language: yaml
2990 """
2991
2992 clog = XML.SubElement(xml_parent, "hudson.plugins.logparser.LogParserPublisher")
2993 clog.set("plugin", "log-parser")
2994 rules_path_element = (
2995 "projectRulePath" if data.get("use-project-rules", True) else "parsingRulesPath"
2996 )
2997 mappings = [
2998 ("unstable-on-warning", "unstableOnWarning", False),
2999 ("fail-on-error", "failBuildOnError", False),
3000 ("show-graphs", "showGraphs", True),
3001 ("use-project-rules", "useProjectRule", True),
3002 ("parse-rules", rules_path_element, ""),
3003 ]
3004 helpers.convert_mapping_to_xml(clog, data, mappings, fail_required=True)
3005
3006
3007 def copy_to_master(registry, xml_parent, data):
3008 """yaml: copy-to-master
3009 Copy files to master from slave.
3010
3011 Requires the Jenkins :jenkins-plugins:`Copy To Slave Plugin <copy-to-slave>`.
3012
3013 :arg list includes: list of file patterns to copy
3014 :arg list excludes: list of file patterns to exclude
3015 :arg str destination: absolute path into which the files will be copied.
3016 If left blank they will be copied into the workspace of the current job
3017 (default '')
3018 :arg bool run-after-result: If this is checked then copying files back to
3019 master will not run until the build result is finalized.(default true)
3020
3021 Example:
3022
3023 .. literalinclude::
3024 /../../tests/publishers/fixtures/copy-to-master001.yaml
3025 :language: yaml
3026 """
3027 cm = XML.SubElement(
3028 xml_parent,
3029 "com.michelin." "cio.hudson.plugins.copytoslave.CopyToMasterNotifier",
3030 )
3031 cm.set("plugin", "copy-to-slave")
3032
3033 XML.SubElement(cm, "includes").text = ",".join(data.get("includes", [""]))
3034 XML.SubElement(cm, "excludes").text = ",".join(data.get("excludes", [""]))
3035 mappings = [
3036 ("run-after-result", "runAfterResultFinalised", True),
3037 ("destination", "destinationFolder", ""),
3038 ]
3039 helpers.convert_mapping_to_xml(cm, data, mappings, fail_required=True)
3040
3041 if data.get("destination", ""):
3042 XML.SubElement(cm, "overrideDestinationFolder").text = "true"
3043
3044
3045 def jira(registry, xml_parent, data):
3046 """yaml: jira
3047 Update relevant JIRA issues
3048 Requires the Jenkins :jenkins-plugins:`JIRA Plugin <jira>`.
3049
3050 Example:
3051
3052 .. literalinclude:: /../../tests/publishers/fixtures/jira001.yaml
3053 :language: yaml
3054 """
3055 XML.SubElement(xml_parent, "hudson.plugins.jira.JiraIssueUpdater")
3056
3057
3058 def growl(registry, xml_parent, data):
3059 """yaml: growl
3060 Push notifications to growl client.
3061 Requires the Jenkins :jenkins-plugins:`Growl Plugin <growl>`.
3062
3063 :arg str ip: IP address to send growl notifications to (required)
3064 :arg bool notify-only-on-fail-or-recovery: send a growl only when build
3065 fails or recovers from a failure (default false)
3066
3067 Minimal Example:
3068
3069 .. literalinclude:: /../../tests/publishers/fixtures/growl-minimal.yaml
3070 :language: yaml
3071
3072 Full Example:
3073
3074 .. literalinclude:: /../../tests/publishers/fixtures/growl-full.yaml
3075 :language: yaml
3076 """
3077 growl = XML.SubElement(xml_parent, "hudson.plugins.growl.GrowlPublisher")
3078 growl.set("plugin", "growl")
3079
3080 mapping = [
3081 ("ip", "IP", None),
3082 ("notify-only-on-fail-or-recovery", "onlyOnFailureOrRecovery", False),
3083 ]
3084 helpers.convert_mapping_to_xml(growl, data, mapping, fail_required=True)
3085
3086
3087 def groovy_postbuild(registry, xml_parent, data):
3088 """yaml: groovy-postbuild
3089 Execute a groovy script.
3090 Requires the Jenkins :jenkins-plugins:`Groovy Postbuild Plugin
3091 <groovy-postbuild>`.
3092
3093 Please pay attention on version of plugin you have installed.
3094 There were incompatible changes between 1.x and 2.x. Please see
3095 :jenkins-plugins:`home page <groovy-postbuild>` of this plugin
3096 for full information including migration process.
3097
3098 :arg str script: The groovy script to execute
3099 :arg list classpath: List of additional classpaths (>=1.6)
3100 :arg str on-failure: In case of script failure leave build as it is
3101 for "nothing" option, mark build as unstable
3102 for "unstable" and mark job as failure for "failed"
3103 (default 'nothing')
3104 :arg bool matrix-parent: Run script for matrix parent only (>=1.9)
3105 (default false)
3106 :arg bool sandbox: Execute script inside of groovy sandbox (>=2.0)
3107 (default false)
3108
3109 Example:
3110
3111 .. literalinclude::
3112 /../../tests/publishers/fixtures/groovy-postbuild001.yaml
3113 :language: yaml
3114 """
3115 logger = logging.getLogger("%s:groovy-postbuild" % __name__)
3116 # Backward compatibility with old format
3117 if isinstance(data, six.string_types):
3118 logger.warning(
3119 "You use deprecated configuration, please follow documentation "
3120 "to change configuration. It is not going to be supported in "
3121 "future releases!"
3122 )
3123 data = {"script": data}
3124 # There are incompatible changes, we need to know version
3125 plugin_ver = registry.get_plugin_version("groovy-postbuild")
3126 # Version specific predicates
3127 matrix_parent_support = plugin_ver >= "1.9"
3128 security_plugin_support = plugin_ver >= "2.0"
3129 extra_classpath_support = plugin_ver >= "1.6"
3130
3131 root_tag = "org.jvnet.hudson.plugins.groovypostbuild.GroovyPostbuildRecorder"
3132 groovy = XML.SubElement(xml_parent, root_tag)
3133
3134 behavior = data.get("on-failure")
3135 XML.SubElement(groovy, "behavior").text = {"unstable": "1", "failed": "2"}.get(
3136 behavior, "0"
3137 )
3138
3139 if matrix_parent_support:
3140 XML.SubElement(groovy, "runForMatrixParent").text = str(
3141 data.get("matrix-parent", False)
3142 ).lower()
3143
3144 classpaths = data.get("classpath", list())
3145 if security_plugin_support:
3146 script = XML.SubElement(groovy, "script")
3147 XML.SubElement(script, "script").text = data.get("script")
3148 XML.SubElement(script, "sandbox").text = str(data.get("sandbox", False)).lower()
3149 if classpaths:
3150 classpath = XML.SubElement(script, "classpath")
3151 for path in classpaths:
3152 script_path = XML.SubElement(classpath, "entry")
3153 XML.SubElement(script_path, "url").text = path
3154 else:
3155 XML.SubElement(groovy, "groovyScript").text = data.get("script")
3156 if extra_classpath_support and classpaths:
3157 classpath = XML.SubElement(groovy, "classpath")
3158 for path in classpaths:
3159 script_path = XML.SubElement(
3160 classpath,
3161 "org.jvnet.hudson.plugins.groovypostbuild." "GroovyScriptPath",
3162 )
3163 XML.SubElement(script_path, "path").text = path
3164
3165
3166 def base_publish_over(
3167 xml_parent,
3168 data,
3169 console_prefix,
3170 plugin_tag,
3171 publisher_tag,
3172 transferset_tag,
3173 retry_tag,
3174 reference_plugin_tag,
3175 is_builder=False,
3176 ):
3177 outer = XML.SubElement(xml_parent, plugin_tag)
3178 # 'Publish over SSH' builder has an extra top delegate element
3179 if xml_parent.tag == "builders" or is_builder:
3180 outer = XML.SubElement(outer, "delegate")
3181
3182 XML.SubElement(outer, "consolePrefix").text = console_prefix
3183 delegate = XML.SubElement(outer, "delegate")
3184 publishers = XML.SubElement(delegate, "publishers")
3185
3186 inner = XML.SubElement(publishers, publisher_tag)
3187 XML.SubElement(inner, "configName").text = data["site"]
3188 XML.SubElement(inner, "verbose").text = str(data.get("verbose", False)).lower()
3189
3190 transfers = XML.SubElement(inner, "transfers")
3191 transfersset = XML.SubElement(transfers, transferset_tag)
3192
3193 XML.SubElement(transfersset, "remoteDirectory").text = data["target"]
3194 XML.SubElement(transfersset, "sourceFiles").text = data["source"]
3195 XML.SubElement(transfersset, "excludes").text = data.get("excludes", "")
3196 XML.SubElement(transfersset, "removePrefix").text = data.get("remove-prefix", "")
3197 XML.SubElement(transfersset, "remoteDirectorySDF").text = str(
3198 data.get("target-is-date-format", False)
3199 ).lower()
3200 XML.SubElement(transfersset, "flatten").text = str(
3201 data.get("flatten", False)
3202 ).lower()
3203 XML.SubElement(transfersset, "cleanRemote").text = str(
3204 data.get("clean-remote", False)
3205 ).lower()
3206
3207 if "command" in data:
3208 XML.SubElement(transfersset, "execCommand").text = data["command"]
3209 if "timeout" in data:
3210 XML.SubElement(transfersset, "execTimeout").text = str(data["timeout"])
3211 if "use-pty" in data:
3212 XML.SubElement(transfersset, "usePty").text = str(
3213 data.get("use-pty", False)
3214 ).lower()
3215
3216 XML.SubElement(inner, "useWorkspaceInPromotion").text = "false"
3217 XML.SubElement(inner, "usePromotionTimestamp").text = "false"
3218
3219 if "retries" in data:
3220 retry = XML.SubElement(inner, "retry", {"class": retry_tag})
3221 XML.SubElement(retry, "retries").text = str(data.get("retries", 0))
3222 XML.SubElement(retry, "retryDelay").text = str(data.get("retry-delay", 10000))
3223
3224 XML.SubElement(delegate, "continueOnError").text = "false"
3225 XML.SubElement(delegate, "failOnError").text = str(
3226 data.get("fail-on-error", False)
3227 ).lower()
3228 XML.SubElement(delegate, "alwaysPublishFromMaster").text = str(
3229 data.get("always-publish-from-master", False)
3230 ).lower()
3231 XML.SubElement(
3232 delegate,
3233 "hostConfigurationAccess",
3234 {"class": reference_plugin_tag, "reference": "../.."},
3235 )
3236
3237 return (outer, transfersset)
3238
3239
3240 def cifs(registry, xml_parent, data):
3241 """yaml: cifs
3242 Upload files via CIFS.
3243 Requires the Jenkins :jenkins-plugins:`Publish over CIFS Plugin
3244 <publish-over-cifs>`.
3245
3246 :arg str site: name of the cifs site/share (required)
3247 :arg str target: destination directory (required)
3248 :arg bool target-is-date-format: whether target is a date format. If true,
3249 raw text should be quoted (default false)
3250 :arg bool clean-remote: should the remote directory be deleted before
3251 transferring files (default false)
3252 :arg str source: source path specifier (required)
3253 :arg str excludes: excluded file pattern (default '')
3254 :arg str remove-prefix: prefix to remove from uploaded file paths
3255 (default '')
3256 :arg bool fail-on-error: fail the build if an error occurs (default false).
3257 :arg bool flatten: only create files on the server, don't create
3258 directories (default false).
3259 :arg bool verbose: adds lots of detail useful for debug to the console
3260 but generally should be left off (default false)
3261 :arg int retries: the number of times to retry this server in the event of
3262 failure (optional)
3263 :arg int retry-delay: the time to wait, in milliseconds, before attempting
3264 another transfer (default 10000)
3265
3266 Minimal Example:
3267
3268 .. literalinclude:: /../../tests/publishers/fixtures/cifs-minimal.yaml
3269 :language: yaml
3270
3271 Full Example:
3272
3273 .. literalinclude:: /../../tests/publishers/fixtures/cifs-full.yaml
3274 :language: yaml
3275
3276 """
3277 console_prefix = "CIFS: "
3278 if xml_parent.tag == "publishers":
3279 plugin_tag = "jenkins.plugins.publish__over__cifs.CifsPublisherPlugin"
3280 is_builder = False
3281 else:
3282 plugin_tag = "jenkins.plugins.publish__over__cifs.CifsBuilderPlugin"
3283 is_builder = True
3284 publisher_tag = "jenkins.plugins.publish__over__cifs.CifsPublisher"
3285 transfer_tag = "jenkins.plugins.publish__over__cifs.CifsTransfer"
3286 retry_tag = "jenkins.plugins.publish_over_cifs.CifsRetry"
3287 plugin_reference_tag = "jenkins.plugins.publish_over_cifs." "CifsPublisherPlugin"
3288 base_publish_over(
3289 xml_parent,
3290 data,
3291 console_prefix,
3292 plugin_tag,
3293 publisher_tag,
3294 transfer_tag,
3295 retry_tag,
3296 plugin_reference_tag,
3297 is_builder,
3298 )
3299
3300
3301 def cigame(registry, xml_parent, data):
3302 """yaml: cigame
3303 This plugin introduces a game where users get points
3304 for improving the builds.
3305 Requires the Jenkins Continuous Integration Game
3306 plugin (:jenkins-github:`ci-game-plugin`).
3307
3308 Example:
3309
3310 .. literalinclude:: /../../tests/publishers/fixtures/cigame.yaml
3311 :language: yaml
3312 """
3313 XML.SubElement(xml_parent, "hudson.plugins.cigame.GamePublisher")
3314
3315
3316 def sonar(registry, xml_parent, data):
3317 """yaml: sonar
3318 Sonar plugin support.
3319 Requires the Jenkins `Sonar Plugin.
3320 <https://docs.sonarsource.com/sonarqube/latest/analyzing-source-code/scanners/jenkins-extension-sonarqube/>`_
3321
3322 :arg str installation-name: name of the Sonar instance to use (optional)
3323 :arg str jdk: JDK to use (inherited from the job if omitted). (optional)
3324 :arg str branch: branch onto which the analysis will be posted (default '')
3325 :arg str language: source code language (default '')
3326 :arg str root-pom: Root POM (default 'pom.xml')
3327 :arg bool private-maven-repo: If true, use private Maven repository.
3328 (default false)
3329 :arg str maven-opts: options given to maven (default '')
3330 :arg str additional-properties: sonar analysis parameters (default '')
3331 :arg str maven-installation-name: the name of the Maven installation
3332 to use (optional)
3333 :arg dict skip-global-triggers:
3334 :Triggers: * **skip-when-scm-change** (`bool`): skip analysis when
3335 build triggered by scm (default false)
3336 * **skip-when-upstream-build** (`bool`): skip analysis when
3337 build triggered by an upstream build (default false)
3338 * **skip-when-envvar-defined** (`str`): skip analysis when
3339 the specified environment variable is set to true
3340 (default '')
3341 :arg str settings: Path to use as user settings.xml. It is possible to
3342 provide a ConfigFileProvider settings file, see Example below.
3343 (optional)
3344 :arg str global-settings: Path to use as global settings.xml. It is
3345 possible to provide a ConfigFileProvider settings file, see Example
3346 below. (optional)
3347
3348 Requires the Jenkins :jenkins-plugins:`Config File Provider Plugin
3349 <config-file-provider>`
3350 for the Config File Provider "settings" and "global-settings" config.
3351
3352 This publisher supports the post-build action exposed by the Jenkins
3353 Sonar Plugin, which is triggering a Sonar Analysis with Maven.
3354
3355 Minimal Example:
3356
3357 .. literalinclude:: /../../tests/publishers/fixtures/sonar-minimal.yaml
3358 :language: yaml
3359
3360 Full Example:
3361
3362 .. literalinclude:: /../../tests/publishers/fixtures/sonar-full.yaml
3363 :language: yaml
3364 """
3365
3366 sonar = XML.SubElement(xml_parent, "hudson.plugins.sonar.SonarPublisher")
3367 sonar.set("plugin", "sonar")
3368 if "installation-name" in data:
3369 XML.SubElement(sonar, "installationName").text = data["installation-name"]
3370 if "jdk" in data:
3371 XML.SubElement(sonar, "jdk").text = data["jdk"]
3372 if "maven-installation-name" in data:
3373 XML.SubElement(sonar, "mavenInstallationName").text = data[
3374 "maven-installation-name"
3375 ]
3376
3377 mappings = [
3378 ("branch", "branch", ""),
3379 ("language", "language", ""),
3380 ("root-pom", "rootPom", "pom.xml"),
3381 ("private-maven-repo", "usePrivateRepository", False),
3382 ("maven-opts", "mavenOpts", ""),
3383 ("additional-properties", "jobAdditionalProperties", ""),
3384 ]
3385 helpers.convert_mapping_to_xml(sonar, data, mappings, fail_required=True)
3386
3387 if "skip-global-triggers" in data:
3388 data_triggers = data["skip-global-triggers"]
3389 triggers = XML.SubElement(sonar, "triggers")
3390 triggers_mappings = [
3391 ("skip-when-scm-change", "skipScmCause", False),
3392 ("skip-when-upstream-build", "skipUpstreamCause", False),
3393 ("skip-when-envvar-defined", "envVar", ""),
3394 ]
3395 helpers.convert_mapping_to_xml(
3396 triggers, data_triggers, triggers_mappings, fail_required=True
3397 )
3398
3399 helpers.config_file_provider_settings(sonar, data)
3400
3401
3402 def sounds(parser, xml_parent, data):
3403 """yaml: sounds
3404 Play audio clips locally through sound hardware,
3405 remotely by piping them through an operating system command,
3406 or simultaneously through all browsers on a Jenkins page.
3407
3408 Requires the Jenkins :jenkins-plugins:`Jenkins Sounds plugin
3409 <sounds>`
3410
3411 :arg dict success: Play on success
3412
3413 :success:
3414 .. _sound_and_cond:
3415
3416 * **sound** (`str`) - Sound name
3417 * **from** (`list`) - Previous build result (default is all)
3418 :from values:
3419 * **success**
3420 * **unstable**
3421 * **failure**
3422 * **not_build**
3423 * **aborted**
3424
3425 :arg dict unstable: Play on unstable.
3426 Specifying sound and conditions see :ref:`above <sound_and_cond>`.
3427 :arg dict failure: Play on failure.
3428 Specifying sound and conditions see :ref:`above <sound_and_cond>`.
3429 :arg dict not_build: Play on not build.
3430 Specifying sound and conditions see :ref:`above <sound_and_cond>`.
3431 :arg dict aborted: Play on aborted.
3432 Specifying sound and conditions see :ref:`above <sound_and_cond>`.
3433
3434 Minimal example using defaults:
3435
3436 .. literalinclude:: /../../tests/publishers/fixtures/sounds001.yaml
3437 :language: yaml
3438
3439 Full example:
3440
3441 .. literalinclude:: /../../tests/publishers/fixtures/sounds003.yaml
3442 :language: yaml
3443 """
3444
3445 mapping_dict = {
3446 "success": hudson_model.SUCCESS,
3447 "unstable": hudson_model.UNSTABLE,
3448 "failure": hudson_model.FAILURE,
3449 "not_build": hudson_model.NOTBUILD,
3450 "aborted": hudson_model.ABORTED,
3451 }
3452 sounds = XML.SubElement(
3453 xml_parent, "net.hurstfrost.hudson." "sounds.HudsonSoundsNotifier"
3454 )
3455 events = XML.SubElement(sounds, "soundEvents")
3456 for status, v in data.items():
3457 try:
3458 model = mapping_dict[status]
3459 except KeyError:
3460 raise InvalidAttributeError("build status", status, mapping_dict)
3461
3462 event = XML.SubElement(
3463 events, "net.hurstfrost.hudson.sounds." "HudsonSoundsNotifier_-SoundEvent"
3464 )
3465 XML.SubElement(event, "soundId").text = v["sound"]
3466 to_result = XML.SubElement(event, "toResult")
3467 XML.SubElement(to_result, "name").text = model["name"]
3468 XML.SubElement(to_result, "ordinal").text = model["ordinal"]
3469 XML.SubElement(to_result, "color").text = model["color"]
3470 XML.SubElement(to_result, "completeBuild").text = str(model["complete"]).lower()
3471
3472 from_results = XML.SubElement(event, "fromResults")
3473 results = ["not_build", "success", "aborted", "failure", "unstable"]
3474 if "from" in v:
3475 results = v["from"]
3476 for result in results:
3477 model = mapping_dict[result]
3478 from_result = XML.SubElement(from_results, "hudson.model.Result")
3479 XML.SubElement(from_result, "name").text = model["name"]
3480 XML.SubElement(from_result, "ordinal").text = model["ordinal"]
3481 XML.SubElement(from_result, "color").text = model["color"]
3482 XML.SubElement(from_result, "completeBuild").text = str(
3483 model["complete"]
3484 ).lower()
3485
3486
3487 def performance(registry, xml_parent, data):
3488 r"""yaml: performance
3489 Publish performance test results from jmeter and junit.
3490 Requires the Jenkins :jenkins-plugins:`Performance Plugin
3491 <performance>`.
3492
3493 :arg int failed-threshold: Specify the error percentage threshold that
3494 set the build failed. A negative value means don't use this threshold
3495 (default 0)
3496 :arg int unstable-threshold: Specify the error percentage threshold that
3497 set the build unstable. A negative value means don't use this threshold
3498 (default 0)
3499 :arg str unstable-response-time-threshold: Average response time threshold
3500 (default '')
3501 :arg float failed-threshold-positive: Maximum failed percentage for build
3502 comparison (default 0.0)
3503 :arg float failed-threshold-negative: Minimum failed percentage for build
3504 comparison (default 0.0)
3505 :arg float unstable-threshold-positive: Maximum unstable percentage for
3506 build comparison (default 0.0)
3507 :arg float unstable-threshold-negative: Minimum unstable percentage for
3508 build comparison (default 0.0)
3509 :arg int nth-build-number: Build number for build comparison (default 0)
3510 :arg bool mode-relative-thresholds: Relative threshold mode (default false)
3511 :arg str config-type: Compare based on (default 'ART')
3512
3513 :config-type values:
3514 * **ART** -- Average Response Time
3515 * **MRT** -- Median Response Time
3516 * **PRT** -- Percentile Response Time
3517
3518 :arg bool mode-of-threshold: Mode of threshold, true for relative threshold
3519 and false for error threshold (default false)
3520 :arg bool fail-build: Fail build when result files are not present
3521 (default false)
3522 :arg bool compare-build-previous: Compare with previous build
3523 (default false)
3524 :arg bool mode-performance-per-test-case: Performance Per Test Case Mode
3525 (default true)
3526 :arg bool mode-thoughput: Show Throughput Chart (default false)
3527
3528 :arg dict report:
3529
3530 :(jmeter or junit): (`dict` or `str`): Specify a custom report file
3531 (optional; jmeter default \**/*.jtl, junit default **/TEST-\*.xml)
3532
3533 Minimal Example:
3534
3535 .. literalinclude::
3536 /../../tests/publishers/fixtures/performance-minimal.yaml
3537 :language: yaml
3538
3539 Full Example:
3540
3541 .. literalinclude::
3542 /../../tests/publishers/fixtures/performance-full.yaml
3543 :language: yaml
3544 """
3545 perf = XML.SubElement(
3546 xml_parent, "hudson.plugins.performance." "PerformancePublisher"
3547 )
3548 perf.set("plugin", "performance")
3549 types = ["ART", "MRT", "PRT"]
3550 mappings = [
3551 ("failed-threshold", "errorFailedThreshold", 0),
3552 ("unstable-threshold", "errorUnstableThreshold", 0),
3553 ("unstable-response-time-threshold", "errorUnstableResponseTimeThreshold", ""),
3554 ("failed-threshold-positive", "relativeFailedThresholdPositive", "0.0"),
3555 ("failed-threshold-negative", "relativeFailedThresholdNegative", "0.0"),
3556 ("unstable-threshold-positive", "relativeUnstableThresholdPositive", "0.0"),
3557 ("unstable-threshold-negative", "relativeUnstableThresholdNegative", "0.0"),
3558 ("nth-build-number", "nthBuildNumber", 0),
3559 ("mode-relative-thresholds", "modeRelativeThresholds", False),
3560 ("config-type", "configType", "ART", types),
3561 ("mode-of-threshold", "modeOfThreshold", False),
3562 ("fail-build", "failBuildIfNoResultFile", False),
3563 ("compare-build-previous", "compareBuildPrevious", False),
3564 ("mode-performance-per-test-case", "modePerformancePerTestCase", True),
3565 ("mode-thoughput", "modeThroughput", False),
3566 ]
3567 helpers.convert_mapping_to_xml(perf, data, mappings, fail_required=True)
3568
3569 parsers = XML.SubElement(perf, "parsers")
3570 if "report" in data:
3571 for item in data["report"]:
3572 if isinstance(item, dict):
3573 item_name = next(iter(item.keys()))
3574 item_values = item.get(item_name, None)
3575 if item_name == "jmeter":
3576 jmhold = XML.SubElement(
3577 parsers, "hudson.plugins." "performance." "JMeterParser"
3578 )
3579 XML.SubElement(jmhold, "glob").text = str(item_values)
3580 elif item_name == "junit":
3581 juhold = XML.SubElement(
3582 parsers, "hudson.plugins." "performance." "JUnitParser"
3583 )
3584 XML.SubElement(juhold, "glob").text = str(item_values)
3585 else:
3586 raise JenkinsJobsException(
3587 "You have not specified jmeter "
3588 "or junit, or you have "
3589 "incorrectly assigned the key "
3590 "value."
3591 )
3592 elif isinstance(item, str):
3593 if item == "jmeter":
3594 jmhold = XML.SubElement(
3595 parsers, "hudson.plugins." "performance." "JMeterParser"
3596 )
3597 XML.SubElement(jmhold, "glob").text = "**/*.jtl"
3598 elif item == "junit":
3599 juhold = XML.SubElement(
3600 parsers, "hudson.plugins." "performance." "JUnitParser"
3601 )
3602 XML.SubElement(juhold, "glob").text = "**/TEST-*.xml"
3603 else:
3604 raise JenkinsJobsException(
3605 "You have not specified jmeter "
3606 "or junit, or you have "
3607 "incorrectly assigned the key "
3608 "value."
3609 )
3610
3611
3612 def join_trigger(registry, xml_parent, data):
3613 """yaml: join-trigger
3614 Trigger a job after all the immediate downstream jobs have completed.
3615 Requires the Jenkins :jenkins-plugins:`Join Plugin <join>`.
3616
3617 :arg list projects: list of projects to trigger
3618 :arg list publishers: list of triggers from publishers module that
3619 defines projects that need to be triggered
3620 :arg str threshold: result threshold to trigger jobs (optional).
3621 Valid values are "success", "unstable", "failure", and "aborted".
3622 :arg bool even-if-unstable: if true jobs will trigger even if some
3623 downstream jobs are marked as unstable (default false) (DEPRECATED)
3624
3625 Example:
3626
3627 .. literalinclude::
3628 /../../tests/publishers/fixtures/join-trigger001.yaml
3629 :language: yaml
3630 """
3631 jointrigger = XML.SubElement(xml_parent, "join.JoinTrigger")
3632
3633 joinProjectsText = ",".join(data.get("projects", [""]))
3634 XML.SubElement(jointrigger, "joinProjects").text = joinProjectsText
3635
3636 publishers = XML.SubElement(jointrigger, "joinPublishers")
3637 for pub in data.get("publishers", []):
3638 for edited_node in create_publishers(registry, pub):
3639 publishers.append(edited_node)
3640
3641 unstable = str(data.get("even-if-unstable", "")).lower()
3642 if unstable:
3643 XML.SubElement(jointrigger, "evenIfDownstreamUnstable").text = unstable
3644
3645 threshold = data.get("threshold", "")
3646 if threshold:
3647 helpers.trigger_threshold(jointrigger, "resultThreshold", threshold)
3648
3649
3650 def jabber(registry, xml_parent, data):
3651 """yaml: jabber
3652 Integrates Jenkins with the Jabber/XMPP instant messaging protocol
3653 Requires the Jenkins :jenkins-plugins:`Jabber Plugin <jabber>`.
3654
3655 :arg bool notify-on-build-start: Whether to send notifications
3656 to channels when a build starts (default false)
3657 :arg bool notify-scm-committers: Whether to send notifications
3658 to the users that are suspected of having broken this build
3659 (default false)
3660 :arg bool notify-scm-culprits: Also send notifications to 'culprits'
3661 from previous unstable/failed builds (default false)
3662 :arg bool notify-upstream-committers: Whether to send notifications to
3663 upstream committers if no committers were found for a broken build
3664 (default false)
3665 :arg bool notify-scm-fixers: Whether to send notifications to the users
3666 that have fixed a broken build (default false)
3667 :arg list group-targets: List of group targets to notify
3668 :arg list individual-targets: List of individual targets to notify
3669 :arg dict strategy: When to send notifications (default all)
3670
3671 :strategy values:
3672 * **all** -- Always
3673 * **failure** -- On any failure
3674 * **failure-fixed** -- On failure and fixes
3675 * **new-failure-fixed** -- On new failure and fixes
3676 * **change** -- Only on state change
3677 :arg dict message: Channel notification message (default summary-scm)
3678
3679 :message values:
3680 * **summary-scm** -- Summary + SCM changes
3681 * **summary** -- Just summary
3682 * **summary-build** -- Summary and build parameters
3683 * **summary-scm-fail** -- Summary, SCM changes, and failed tests
3684
3685 Minimal Example:
3686
3687 .. literalinclude::
3688 /../../tests/publishers/fixtures/jabber-minimal.yaml
3689 :language: yaml
3690
3691 Full Example:
3692
3693 .. literalinclude:: /../../tests/publishers/fixtures/jabber-full.yaml
3694 :language: yaml
3695 """
3696 j = XML.SubElement(
3697 xml_parent, "hudson.plugins.jabber.im.transport." "JabberPublisher"
3698 )
3699 j.set("plugin", "jabber")
3700
3701 t = XML.SubElement(j, "targets")
3702 if "group-targets" in data:
3703 for group in data["group-targets"]:
3704 gcimt = XML.SubElement(t, "hudson.plugins.im." "GroupChatIMMessageTarget")
3705 gcimt.set("plugin", "instant-messaging")
3706 XML.SubElement(gcimt, "name").text = group
3707 XML.SubElement(gcimt, "notificationOnly").text = "false"
3708 if "individual-targets" in data:
3709 for individual in data["individual-targets"]:
3710 dimt = XML.SubElement(t, "hudson.plugins.im." "DefaultIMMessageTarget")
3711 dimt.set("plugin", "instant-messaging")
3712 XML.SubElement(dimt, "value").text = individual
3713 strategy = data.get("strategy", "all")
3714 strategydict = {
3715 "all": "ALL",
3716 "failure": "ANY_FAILURE",
3717 "failure-fixed": "FAILURE_AND_FIXED",
3718 "new-failure-fixed": "NEW_FAILURE_AND_FIXED",
3719 "change": "STATECHANGE_ONLY",
3720 }
3721 if strategy not in strategydict:
3722 raise JenkinsJobsException(
3723 "Strategy entered is not valid, must be "
3724 + "one of: all, failure, failure-fixed, or "
3725 "change"
3726 )
3727 XML.SubElement(j, "strategy").text = strategydict[strategy]
3728
3729 mappings = [
3730 ("notify-on-build-start", "notifyOnBuildStart", False),
3731 ("notify-scm-committers", "notifySuspects", False),
3732 ("notify-scm-culprits", "notifyCulprits", False),
3733 ("notify-scm-fixers", "notifyFixers", False),
3734 ("notify-upstream-committers", "notifyUpstreamCommitters", False),
3735 ]
3736 helpers.convert_mapping_to_xml(j, data, mappings, fail_required=True)
3737
3738 message = data.get("message", "summary-scm")
3739 messagedict = {
3740 "summary-scm": "DefaultBuildToChatNotifier",
3741 "summary": "SummaryOnlyBuildToChatNotifier",
3742 "summary-build": "BuildParametersBuildToChatNotifier",
3743 "summary-scm-fail": "PrintFailingTestsBuildToChatNotifier",
3744 }
3745 if message not in messagedict:
3746 raise JenkinsJobsException(
3747 "Message entered is not valid, must be one "
3748 "of: summary-scm, summary, summary-build "
3749 "or summary-scm-fail"
3750 )
3751 XML.SubElement(
3752 j,
3753 "buildToChatNotifier",
3754 {"class": "hudson.plugins.im.build_notify." + messagedict[message]},
3755 )
3756 XML.SubElement(j, "matrixMultiplier").text = "ONLY_CONFIGURATIONS"
3757
3758
3759 def workspace_cleanup(registry, xml_parent, data):
3760 """yaml: workspace-cleanup (post-build)
3761
3762 Requires the Jenkins :jenkins-plugins:`Workspace Cleanup Plugin
3763 <ws-cleanup>`.
3764
3765 The pre-build workspace-cleanup is available as a wrapper.
3766
3767 :arg list include: list of files to be included
3768 :arg list exclude: list of files to be excluded
3769 :arg bool dirmatch: Apply pattern to directories too (default false)
3770 :arg list clean-if: clean depending on build status
3771
3772 :clean-if values:
3773 * **success** (`bool`) (default true)
3774 * **unstable** (`bool`) (default true)
3775 * **failure** (`bool`) (default true)
3776 * **aborted** (`bool`) (default true)
3777 * **not-built** (`bool`) (default true)
3778 :arg bool fail-build: Fail the build if the cleanup fails (default true)
3779 :arg bool clean-parent: Cleanup matrix parent workspace (default false)
3780 :arg str external-deletion-command: external deletion command to run
3781 against files and directories
3782 :arg bool disable-deferred-wipeout: Disable improved deferred wipeout
3783 method (default false)
3784
3785 Minimal Example:
3786
3787 .. literalinclude::
3788 /../../tests/publishers/fixtures/workspace-cleanup-minimal.yaml
3789 :language: yaml
3790
3791 Full Example:
3792
3793 .. literalinclude::
3794 /../../tests/publishers/fixtures/workspace-cleanup-full.yaml
3795 :language: yaml
3796 """
3797
3798 p = XML.SubElement(xml_parent, "hudson.plugins.ws__cleanup.WsCleanup")
3799 p.set("plugin", "ws-cleanup")
3800 if "include" in data or "exclude" in data:
3801 patterns = XML.SubElement(p, "patterns")
3802
3803 for inc in data.get("include", []):
3804 ptrn = XML.SubElement(patterns, "hudson.plugins.ws__cleanup.Pattern")
3805 XML.SubElement(ptrn, "pattern").text = inc
3806 XML.SubElement(ptrn, "type").text = "INCLUDE"
3807
3808 for exc in data.get("exclude", []):
3809 ptrn = XML.SubElement(patterns, "hudson.plugins.ws__cleanup.Pattern")
3810 XML.SubElement(ptrn, "pattern").text = exc
3811 XML.SubElement(ptrn, "type").text = "EXCLUDE"
3812
3813 mappings = [
3814 ("dirmatch", "deleteDirs", False),
3815 ("clean-parent", "cleanupMatrixParent", False),
3816 ("external-deletion-command", "externalDelete", ""),
3817 ("disable-deferred-wipeout", "disableDeferredWipeout", False),
3818 ]
3819 helpers.convert_mapping_to_xml(p, data, mappings, fail_required=True)
3820
3821 mask = [
3822 ("success", "cleanWhenSuccess"),
3823 ("unstable", "cleanWhenUnstable"),
3824 ("failure", "cleanWhenFailure"),
3825 ("not-built", "cleanWhenNotBuilt"),
3826 ("aborted", "cleanWhenAborted"),
3827 ]
3828 clean = data.get("clean-if", [])
3829 cdict = dict()
3830 for d in clean:
3831 cdict.update(d)
3832 for k, v in mask:
3833 XML.SubElement(p, v).text = str(cdict.pop(k, True)).lower()
3834
3835 if len(cdict) > 0:
3836 raise ValueError("clean-if must be one of: %r" % list(mask.keys()))
3837
3838 if str(data.get("fail-build", False)).lower() == "false":
3839 XML.SubElement(p, "notFailBuild").text = "true"
3840 else:
3841 XML.SubElement(p, "notFailBuild").text = "false"
3842
3843
3844 def maven_deploy(registry, xml_parent, data):
3845 """yaml: maven-deploy
3846 Deploy artifacts to Maven repository.
3847
3848 :arg str id: Repository ID
3849 :arg str url: Repository URL (optional)
3850 :arg bool unique-version: Assign unique versions to snapshots
3851 (default true)
3852 :arg bool deploy-unstable: Deploy even if the build is unstable
3853 (default false)
3854 :arg str release-env-var: If the given variable name is set to "true",
3855 the deploy steps are skipped. (optional)
3856
3857
3858 Example:
3859
3860 .. literalinclude:: /../../tests/publishers/fixtures/maven-deploy001.yaml
3861 :language: yaml
3862 """
3863
3864 p = XML.SubElement(xml_parent, "hudson.maven.RedeployPublisher")
3865 if "id" in data:
3866 XML.SubElement(p, "id").text = data["id"]
3867 if "url" in data:
3868 XML.SubElement(p, "url").text = data["url"]
3869 XML.SubElement(p, "uniqueVersion").text = str(
3870 data.get("unique-version", True)
3871 ).lower()
3872 XML.SubElement(p, "evenIfUnstable").text = str(
3873 data.get("deploy-unstable", False)
3874 ).lower()
3875 if "release-env-var" in data:
3876 XML.SubElement(p, "releaseEnvVar").text = data["release-env-var"]
3877
3878
3879 def artifactory(registry, xml_parent, data):
3880 """yaml: artifactory
3881 Uses/requires the Artifactory plugin to deploy artifacts to
3882 Artifactory Server.
3883
3884 Requires the Jenkins :jenkins-plugins:`Artifactory Plugin
3885 <artifactory>`.
3886
3887 :arg str url: Artifactory server url (default '')
3888 :arg str name: Artifactory user with permissions use for
3889 connected to the selected Artifactory Server (default '')
3890 :arg str release-repo-key: Release repository name (default '')
3891 :arg str snapshot-repo-key: Snapshots repository name (default '')
3892 :arg bool publish-build-info: Push build metadata with artifacts
3893 (default false)
3894 :arg bool discard-old-builds:
3895 Remove older build info from Artifactory (default false)
3896 :arg bool discard-build-artifacts:
3897 Remove older build artifacts from Artifactory (default false)
3898 :arg bool even-if-unstable: Deploy artifacts even when the build
3899 is unstable (default false)
3900 :arg bool run-checks: Run automatic license scanning check after the
3901 build is complete (default false)
3902 :arg bool include-publish-artifacts: Include the build's published
3903 module artifacts in the license violation checks if they are
3904 also used as dependencies for other modules in this build
3905 (default false)
3906 :arg bool pass-identified-downstream: When true, a build parameter
3907 named ARTIFACTORY_BUILD_ROOT with a value of
3908 ${JOB_NAME}-${BUILD_NUMBER} will be sent to downstream builds
3909 (default false)
3910 :arg bool license-auto-discovery: Tells Artifactory not to try
3911 and automatically analyze and tag the build's dependencies
3912 with license information upon deployment (default true)
3913 :arg bool enable-issue-tracker-integration: When the Jenkins
3914 JIRA plugin is enabled, synchronize information about JIRA
3915 issues to Artifactory and attach issue information to build
3916 artifacts (default false)
3917 :arg bool aggregate-build-issues: When the Jenkins JIRA plugin
3918 is enabled, include all issues from previous builds up to the
3919 latest build status defined in "Aggregation Build Status"
3920 (default false)
3921 :arg bool allow-promotion-of-non-staged-builds: The build
3922 promotion operation will be available to all successful builds
3923 instead of only staged ones (default false)
3924 :arg bool filter-excluded-artifacts-from-build: Add the excluded
3925 files to the excludedArtifacts list and remove them from the
3926 artifacts list in the build info (default false)
3927 :arg str scopes: A list of dependency scopes/configurations to run
3928 license violation checks on. If left empty all dependencies from
3929 all scopes will be checked (default '')
3930 :arg str violation-recipients: Recipients that need to be notified
3931 of license violations in the build info (default '')
3932 :arg list matrix-params: Semicolon-separated list of properties to
3933 attach to all deployed artifacts in addition to the default ones:
3934 build.name, build.number, and vcs.revision (default [])
3935 :arg str black-duck-app-name: The existing Black Duck Code Center
3936 application name (default '')
3937 :arg str black-duck-app-version: The existing Black Duck Code Center
3938 application version (default '')
3939 :arg str black-duck-report-recipients: Recipients that will be emailed
3940 a report after the automatic Black Duck Code Center compliance checks
3941 finished (default '')
3942 :arg str black-duck-scopes: A list of dependency scopes/configurations
3943 to run Black Duck Code Center compliance checks on. If left empty
3944 all dependencies from all scopes will be checked (default '')
3945 :arg bool black-duck-run-checks: Automatic Black Duck Code Center
3946 compliance checks will occur after the build completes
3947 (default false)
3948 :arg bool black-duck-include-published-artifacts: Include the build's
3949 published module artifacts in the license violation checks if they
3950 are also used as dependencies for other modules in this build
3951 (default false)
3952 :arg bool auto-create-missing-component-requests: Auto create
3953 missing components in Black Duck Code Center application after
3954 the build is completed and deployed in Artifactory
3955 (default true)
3956 :arg bool auto-discard-stale-component-requests: Auto discard
3957 stale components in Black Duck Code Center application after
3958 the build is completed and deployed in Artifactory
3959 (default true)
3960 :arg bool deploy-artifacts: Push artifacts to the Artifactory
3961 Server. Use deployment-include-patterns and
3962 deployment-exclude-patterns to filter deploy artifacts. (default true)
3963 :arg list deployment-include-patterns: New line or comma separated mappings
3964 of build artifacts to published artifacts. Supports Ant-style wildcards
3965 mapping to target directories. E.g.: */*.zip=>dir (default [])
3966 :arg list deployment-exclude-patterns: New line or comma separated patterns
3967 for excluding artifacts from deployment to Artifactory (default [])
3968 :arg bool env-vars-include: Include all environment variables
3969 accessible by the build process. Jenkins-specific env variables
3970 are always included. Use env-vars-include-patterns and
3971 env-vars-exclude-patterns to filter variables to publish,
3972 (default false)
3973 :arg list env-vars-include-patterns: Comma or space-separated list of
3974 environment variables that will be included as part of the published
3975 build info. Environment variables may contain the * and the ? wildcards
3976 (default [])
3977 :arg list env-vars-exclude-patterns: Comma or space-separated list of
3978 environment variables that will be excluded from the published
3979 build info (default [])
3980
3981 Example:
3982
3983 .. literalinclude:: /../../tests/publishers/fixtures/artifactory01.yaml
3984
3985 .. literalinclude:: /../../tests/publishers/fixtures/artifactory02.yaml
3986
3987 """
3988
3989 artifactory = XML.SubElement(
3990 xml_parent, "org.jfrog.hudson.ArtifactoryRedeployPublisher"
3991 )
3992
3993 # optional_props
3994 helpers.artifactory_optional_props(artifactory, data, "publishers")
3995
3996 XML.SubElement(artifactory, "matrixParams").text = ",".join(
3997 data.get("matrix-params", [])
3998 )
3999
4000 # details
4001 details = XML.SubElement(artifactory, "details")
4002 helpers.artifactory_common_details(details, data)
4003
4004 mapping = [
4005 ("release-repo-key", "repositoryKey", ""),
4006 ("snapshot-repo-key", "snapshotsRepositoryKey", ""),
4007 ]
4008 helpers.convert_mapping_to_xml(details, data, mapping, fail_required=True)
4009
4010 plugin = XML.SubElement(details, "stagingPlugin")
4011 XML.SubElement(plugin, "pluginName").text = "None"
4012
4013 # artifactDeploymentPatterns
4014 helpers.artifactory_deployment_patterns(artifactory, data)
4015
4016 # envVarsPatterns
4017 helpers.artifactory_env_vars_patterns(artifactory, data)
4018
4019
4020 def test_fairy(registry, xml_parent, data):
4021 """yaml: test-fairy
4022 This plugin helps you to upload Android APKs or iOS IPA files to
4023 www.testfairy.com.
4024
4025 Requires the Jenkins :jenkins-plugins:`Test Fairy Plugin
4026 <TestFairy>`.
4027
4028 :arg str platform: Select platform to upload to, **android** or **ios**
4029 (required)
4030
4031 Android Only:
4032
4033 :arg str proguard-file: Path to Proguard file. Path of mapping.txt from
4034 your proguard output directory. (default '')
4035 :arg str storepass: Password for the keystore (default android)
4036 :arg str alias: alias for key (default androiddebugkey)
4037 :arg str keypass: password for the key (default '')
4038 :arg str keystorepath: Path to Keystore file (required)
4039
4040 IOS Only:
4041
4042 :arg str dSYM-file: Path to .dSYM.zip file (default '')
4043
4044 All:
4045
4046 :arg str apikey: TestFairy API_KEY. Find it in your TestFairy account
4047 settings (required)
4048 :arg str appfile: Path to App file (.apk) or (.ipa). For example:
4049 $WORKSPACE/[YOUR_FILE_NAME].apk or full path to the apk file.
4050 (required)
4051 :arg str tester-groups: Tester groups to notify (default '')
4052 :arg bool notify-testers: Send email with changelogs to testers
4053 (default false)
4054 :arg bool autoupdate: Automatic update (default false)
4055 :arg str max-duration: Duration of the session (default 10m)
4056
4057 :max-duration values:
4058 * **10m**
4059 * **60m**
4060 * **300m**
4061 * **1440m**
4062 :arg bool record-on-background: Record on background (default false)
4063 :arg bool data-only-wifi: Record data only in wifi (default false)
4064 :arg bool video-enabled: Record video (default true)
4065 :arg int screenshot-interval: Time interval between screenshots
4066 (default 1)
4067
4068 :screenshot-interval values:
4069 * **1**
4070 * **2**
4071 * **5**
4072 :arg str video-quality: Video quality (default high)
4073
4074 :video-quality values:
4075 * **high**
4076 * **medium**
4077 * **low**
4078 :arg bool cpu: Enable CPU metrics (default true)
4079 :arg bool memory: Enable memory metrics (default true)
4080 :arg bool logs: Enable logs metrics (default true)
4081 :arg bool network: Enable network metrics (default false)
4082 :arg bool phone-signal: Enable phone signal metrics (default false)
4083 :arg bool wifi: Enable wifi metrics (default false)
4084 :arg bool gps: Enable gps metrics (default false)
4085 :arg bool battery: Enable battery metrics (default false)
4086 :arg bool opengl: Enable opengl metrics (default false)
4087
4088 Example:
4089
4090 .. literalinclude::
4091 /../../tests/publishers/fixtures/test-fairy-android-minimal.yaml
4092 :language: yaml
4093
4094 .. literalinclude::
4095 /../../tests/publishers/fixtures/test-fairy-android001.yaml
4096 :language: yaml
4097
4098 .. literalinclude::
4099 /../../tests/publishers/fixtures/test-fairy-ios-minimal.yaml
4100 :language: yaml
4101
4102 .. literalinclude::
4103 /../../tests/publishers/fixtures/test-fairy-ios001.yaml
4104 :language: yaml
4105 """
4106 platform = data.get("platform")
4107 valid_platforms = ["android", "ios"]
4108
4109 if "platform" not in data:
4110 raise MissingAttributeError("platform")
4111 if platform == "android":
4112 root = XML.SubElement(
4113 xml_parent, "org.jenkinsci.plugins.testfairy.TestFairyAndroidRecorder"
4114 )
4115 helpers.test_fairy_common(root, data)
4116
4117 mappings = [
4118 ("proguard-file", "mappingFile", ""),
4119 ("keystorepath", "keystorePath", None),
4120 ("storepass", "storepass", "android"),
4121 ("alias", "alias", "androiddebugkey"),
4122 ("keypass", "keypass", ""),
4123 ]
4124 helpers.convert_mapping_to_xml(root, data, mappings, fail_required=True)
4125 elif platform == "ios":
4126 root = XML.SubElement(
4127 xml_parent, "org.jenkinsci.plugins.testfairy.TestFairyIosRecorder"
4128 )
4129 helpers.test_fairy_common(root, data)
4130
4131 mappings = [("dSYM-file", "mappingFile", "")]
4132 helpers.convert_mapping_to_xml(root, data, mappings, fail_required=True)
4133 else:
4134 raise InvalidAttributeError("platform", platform, valid_platforms)
4135
4136
4137 def text_finder(registry, xml_parent, data):
4138 """yaml: text-finder
4139 This plugin lets you search keywords in the files you specified and
4140 additionally check build status
4141
4142 Requires the Jenkins :jenkins-plugins:`Text-finder Plugin
4143 <text-finder>`.
4144
4145 :arg str regexp: Specify a regular expression (required)
4146 :arg str fileset: Specify the path to search (optional)
4147 :arg bool also-check-console-output:
4148 Search the console output (default false)
4149 :arg bool succeed-if-found:
4150 Force a build to succeed if a string was found (default false)
4151 :arg bool unstable-if-found:
4152 Set build unstable instead of failing the build (default false)
4153 :arg bool not-built-if-found:
4154 Set build to "Not Built" instead of failing the build (default false)
4155
4156 Example:
4157
4158 .. literalinclude:: /../../tests/publishers/fixtures/text-finder001.yaml
4159 :language: yaml
4160 """
4161
4162 finder = XML.SubElement(xml_parent, "hudson.plugins.textfinder.TextFinderPublisher")
4163 finder.set("plugin", "text-finder")
4164 if "fileset" in data:
4165 XML.SubElement(finder, "fileSet").text = data["fileset"]
4166 mappings = [
4167 ("regexp", "regexp", None),
4168 ("also-check-console-output", "alsoCheckConsoleOutput", False),
4169 ("succeed-if-found", "succeedIfFound", False),
4170 ("unstable-if-found", "unstableIfFound", False),
4171 ("not-built-if-found", "notBuiltIfFound", False),
4172 ]
4173 helpers.convert_mapping_to_xml(finder, data, mappings, fail_required=True)
4174
4175
4176 def html_publisher(registry, xml_parent, data):
4177 """yaml: html-publisher
4178 This plugin publishes HTML reports.
4179
4180 Requires the Jenkins :jenkins-plugins:`HTML Publisher Plugin
4181 <htmlpublisher>`.
4182
4183 :arg str name: Report name (required)
4184 :arg str dir: HTML directory to archive (required)
4185 :arg str files: Specify the pages to display (required)
4186 :arg bool keep-all: keep HTML reports for each past build (default false)
4187 :arg bool allow-missing: Allow missing HTML reports (default false)
4188 :arg bool link-to-last-build: If this and 'keep-all' both are true, it
4189 publishes the link on project level even if build failed.
4190 (default false)
4191
4192
4193 Example:
4194
4195 .. literalinclude:: /../../tests/publishers/fixtures/html-publisher001.yaml
4196 :language: yaml
4197 """
4198
4199 reporter = XML.SubElement(xml_parent, "htmlpublisher.HtmlPublisher")
4200 targets = XML.SubElement(reporter, "reportTargets")
4201 ptarget = XML.SubElement(targets, "htmlpublisher.HtmlPublisherTarget")
4202
4203 mapping = [
4204 ("name", "reportName", None),
4205 ("dir", "reportDir", None),
4206 ("files", "reportFiles", None),
4207 ("link-to-last-build", "alwaysLinkToLastBuild", False),
4208 ("keep-all", "keepAll", False),
4209 ("allow-missing", "allowMissing", False),
4210 ]
4211 helpers.convert_mapping_to_xml(ptarget, data, mapping, fail_required=True)
4212 XML.SubElement(ptarget, "wrapperName").text = "htmlpublisher-wrapper.html"
4213
4214
4215 def rich_text_publisher(registry, xml_parent, data):
4216 """yaml: rich-text-publisher
4217 This plugin puts custom rich text message to the Build pages and Job main
4218 page.
4219
4220 Requires the Jenkins :jenkins-plugins:`Rich Text Publisher Plugin
4221 <rich-text-publisher-plugin>`.
4222
4223 :arg str stable-text: The stable text (required)
4224 :arg str unstable-text: The unstable text if different from stable
4225 (default '')
4226 :arg bool unstable-as-stable: The same text block is used for stable and
4227 unstable builds (default true)
4228 :arg str failed-text: The failed text if different from stable (default '')
4229 :arg bool failed-as-stable: The same text block is used for stable and
4230 failed builds (default true)
4231 :arg str parser-name: HTML, Confluence or WikiText (default 'WikiText')
4232
4233
4234 Minimal Example:
4235
4236 .. literalinclude:: /../../tests/publishers/fixtures/richtext-minimal.yaml
4237 :language: yaml
4238
4239 Full Example:
4240
4241 .. literalinclude::
4242 /../../tests/publishers/fixtures/richtext-full.yaml
4243 :language: yaml
4244 """
4245
4246 parsers = ["HTML", "Confluence", "WikiText"]
4247 reporter = XML.SubElement(
4248 xml_parent, "org.korosoft.jenkins.plugin.rtp.RichTextPublisher"
4249 )
4250 reporter.set("plugin", "rich-text-publisher-plugin")
4251
4252 mappings = [
4253 ("stable-text", "stableText", None),
4254 ("unstable-text", "unstableText", ""),
4255 ("failed-text", "failedText", ""),
4256 ("unstable-as-stable", "unstableAsStable", True),
4257 ("failed-as-stable", "failedAsStable", True),
4258 ("parser-name", "parserName", "WikiText", parsers),
4259 ]
4260 helpers.convert_mapping_to_xml(reporter, data, mappings, fail_required=True)
4261
4262
4263 def tap(registry, xml_parent, data):
4264 """yaml: tap
4265 Adds support to TAP test result files
4266
4267 Requires the Jenkins :jenkins-plugins:`TAP Plugin <tap>`.
4268
4269 :arg str results: TAP test result files (required)
4270 :arg bool fail-if-no-results: Fail if no result (default false)
4271 :arg bool failed-tests-mark-build-as-failure:
4272 Mark build as failure if test fails (default false)
4273 :arg bool output-tap-to-console: Output tap to console (default true)
4274 :arg bool enable-subtests: Enable subtests (default true)
4275 :arg bool discard-old-reports: Discard old reports (default false)
4276 :arg bool todo-is-failure: Handle TODO's as failures (default true)
4277 :arg bool include-comment-diagnostics: Include comment diagnostics (#) in
4278 the results table (>=1.12) (default false)
4279 :arg bool validate-tests: Validate number of tests (>=1.13) (default false)
4280 :arg bool plan-required: TAP plan required? (>=1.17) (default true)
4281 :arg bool verbose: Print a message for each TAP stream file (>=1.17)
4282 (default true)
4283 :arg bool show-only-failures: show only test failures (>=1.17)
4284 (default false)
4285 :arg bool strip-single-parents: (>=2.0) (default false)
4286 :arg bool flatten-tap-result: flattent multiple subtest levels into a
4287 single file (>=2.0) (default false)
4288 :arg bool skip-if-built-not-ok: skip publishing TAP results when
4289 build fails (>= 2.0.1) (default false)
4290 :arg bool remove-yaml-if-corrupted: Remove corrupted YAML (>=2.3)
4291 (default false)
4292
4293 Full Example:
4294
4295 .. literalinclude:: /../../tests/publishers/fixtures/tap-full.yaml
4296 :language: yaml
4297
4298 Minimal Example:
4299
4300 .. literalinclude:: /../../tests/publishers/fixtures/tap-minimal.yaml
4301 :language: yaml
4302 """
4303
4304 tap = XML.SubElement(xml_parent, "org.tap4j.plugin.TapPublisher")
4305 tap.set("plugin", "tap")
4306
4307 mappings = [
4308 ("results", "testResults", None),
4309 ("fail-if-no-results", "failIfNoResults", False),
4310 ("failed-tests-mark-build-as-failure", "failedTestsMarkBuildAsFailure", False),
4311 ("output-tap-to-console", "outputTapToConsole", True),
4312 ("enable-subtests", "enableSubtests", True),
4313 ("discard-old-reports", "discardOldReports", False),
4314 ("todo-is-failure", "todoIsFailure", True),
4315 ("include-comment-diagnostics", "includeCommentDiagnostics", False),
4316 ("validate-tests", "validateNumberOfTests", False),
4317 ("plan-required", "planRequired", True),
4318 ("verbose", "verbose", True),
4319 ("show-only-failures", "showOnlyFailures", False),
4320 ("strip-single-parents", "stripSingleParents", False),
4321 ("flatten-tap-result", "flattenTapResult", False),
4322 ("skip-if-build-not-ok", "skipIfBuildNotOk", False),
4323 ("remove-yaml-if-corrupted", "removeYamlIfCorrupted", False),
4324 ]
4325 helpers.convert_mapping_to_xml(tap, data, mappings, fail_required=True)
4326
4327
4328 def post_tasks(registry, xml_parent, data):
4329 """yaml: post-tasks
4330 Adds support to post build task plugin
4331
4332 Requires the Jenkins :jenkins-plugins:`Post Build Task plugin
4333 <postbuild-task>`.
4334
4335 :arg dict task: Post build task definition
4336 :arg list task[matches]: list of matches when to run the task
4337 :arg dict task[matches][*]: match definition
4338 :arg str task[matches][*][log-text]: text to match against the log
4339 :arg str task[matches][*][operator]: operator to apply with the next match
4340
4341 :task[matches][*][operator] values (default 'AND'):
4342 * **AND**
4343 * **OR**
4344
4345 :arg bool task[escalate-status]: Escalate the task status to the job
4346 (default 'false')
4347 :arg bool task[run-if-job-successful]: Run only if the job was successful
4348 (default 'false')
4349 :arg str task[script]: Shell script to run (default '')
4350
4351 Example:
4352
4353 .. literalinclude:: /../../tests/publishers/fixtures/post-tasks001.yaml
4354 :language: yaml
4355 """
4356
4357 pb_xml = XML.SubElement(xml_parent, "hudson.plugins.postbuildtask.PostbuildTask")
4358 tasks_xml = XML.SubElement(pb_xml, "tasks")
4359 for task in data:
4360 task_xml = XML.SubElement(
4361 tasks_xml, "hudson.plugins.postbuildtask.TaskProperties"
4362 )
4363 matches_xml = XML.SubElement(task_xml, "logTexts")
4364 for match in task.get("matches", []):
4365 lt_xml = XML.SubElement(
4366 matches_xml, "hudson.plugins.postbuildtask.LogProperties"
4367 )
4368 XML.SubElement(lt_xml, "logText").text = str(
4369 match.get("log-text", False) or ""
4370 )
4371 XML.SubElement(lt_xml, "operator").text = str(
4372 match.get("operator", "AND")
4373 ).upper()
4374 mapping = [
4375 ("escalate-status", "EscalateStatus", False),
4376 ("run-if-job-successful", "RunIfJobSuccessful", False),
4377 ("script", "script", ""),
4378 ]
4379 helpers.convert_mapping_to_xml(task_xml, task, mapping, fail_required=True)
4380
4381
4382 def postbuildscript(registry, xml_parent, data):
4383 """yaml: postbuildscript
4384 Executes additional builders, script or Groovy after the build is
4385 complete.
4386
4387 Requires the Jenkins :jenkins-plugins:`Post Build Script plugin
4388 <postbuildscript>`.
4389
4390 :arg list generic-script: Series of Batch/Shell scripts to to run
4391
4392 :generic-script: * **file-path** (`str`) - Path to Batch/Shell scripts
4393 * **role** (`str`) - Execute scripts on. One of
4394 MASTER / SLAVE / BOTH. (default 'BOTH')
4395 * **build-on** (`list`) - Build statuses which trigger
4396 the scripts. Valid options:
4397 SUCCESS / UNSTABLE / FAILURE / NOT_BUILT / ABORTED
4398 (default 'SUCCESS')
4399 * ** execute-on (`str`) - For matrix projects, scripts
4400 can be run after each axis is built (`axes`), after
4401 all axis of the matrix are built (`matrix`) or after
4402 each axis AND the matrix are built (`both`). (default `both`)
4403
4404 :arg list groovy-script: Paths to Groovy scripts
4405
4406 :groovy-script: * **file-path** (`str`) - Path to Groovy scripts
4407 * **role** (`str`) - Execute scripts on. One of
4408 MASTER / SLAVE / BOTH. (default 'BOTH')
4409 * **build-on** (`list`) - Build statuses which trigger
4410 the scripts. Valid options:
4411 SUCCESS / UNSTABLE / FAILURE / NOT_BUILT / ABORTED
4412 (default 'SUCCESS')
4413 * ** execute-on (`str`) - For matrix projects, scripts
4414 can be run after each axis is built (`axes`), after
4415 all axis of the matrix are built (`matrix`) or after
4416 each axis AND the matrix are built (`both`). (default `both`)
4417
4418 :arg list groovy: Inline Groovy
4419
4420 :groovy: * **content** (`str`) - Inline Groovy script.
4421 * **role** (`str`) - Execute scripts on. One of
4422 MASTER / SLAVE / BOTH. (default 'BOTH')
4423 * **build-on** (`list`) - Build statuses which trigger
4424 the scripts. Valid options:
4425 SUCCESS / UNSTABLE / FAILURE / NOT_BUILT / ABORTED
4426 (default 'SUCCESS')
4427 * ** execute-on (`str`) - For matrix projects, scripts
4428 can be run after each axis is built (`axes`), after
4429 all axis of the matrix are built (`matrix`) or after
4430 each axis AND the matrix are built (`both`). (default `both`)
4431
4432 :arg list builders: Execute any number of supported Jenkins builders.
4433
4434 :builders: * **build-steps** (`str`) - Any supported builders,
4435 see :doc:`builders`.
4436 * **role** (`str`) - Execute scripts on. One of
4437 MASTER / SLAVE / BOTH. (default 'BOTH')
4438 * **build-on** (`list`) - Build statuses which trigger
4439 the scripts. Valid options:
4440 SUCCESS / UNSTABLE / FAILURE / NOT_BUILT / ABORTED
4441 (default 'SUCCESS')
4442 * ** execute-on (`str`) - For matrix projects, scripts
4443 can be run after each axis is built (`axes`), after
4444 all axis of the matrix are built (`matrix`) or after
4445 each axis AND the matrix are built (`both`). (default `both`)
4446
4447 :arg bool mark-unstable-if-failed: Build will be marked unstable
4448 if job will be successfully completed but publishing script will return
4449 non zero exit code (default false)
4450
4451 Deprecated Options for versions < 2.0 of plugin:
4452
4453 :arg bool onsuccess: Deprecated, replaced with script-only-if-succeeded
4454 :arg bool script-only-if-succeeded: Scripts and builders are run only if
4455 the build succeeded (default true)
4456 :arg bool onfailure: Deprecated, replaced with script-only-if-failed
4457 :arg bool script-only-if-failed: Scripts and builders are run only if the
4458 build failed (default false)
4459 :arg str execute-on: For matrix projects, scripts can be run after each
4460 axis is built (`axes`), after all axis of the matrix are built
4461 (`matrix`) or after each axis AND the matrix are built (`both`).
4462
4463 The `script-only-if-succeeded` and `bool script-only-if-failed` options are
4464 confusing. If you want the post build to always run regardless of the build
4465 status, you should set them both to `false`.
4466
4467 Minimal Example:
4468
4469 .. literalinclude::
4470 /../../tests/publishers/fixtures/postbuildscript-minimal.yaml
4471 :language: yaml
4472
4473 Full Example:
4474
4475 .. literalinclude::
4476 /../../tests/publishers/fixtures/postbuildscript-full.yaml
4477 :language: yaml
4478
4479 Example(s) versions < 2.0:
4480
4481 .. literalinclude::
4482 /../../tests/publishers/fixtures/postbuildscript001.yaml
4483 :language: yaml
4484
4485 You can also execute :doc:`builders </builders>`:
4486
4487 .. literalinclude::
4488 /../../tests/publishers/fixtures/postbuildscript002.yaml
4489 :language: yaml
4490
4491 Run once after the whole matrix (all axes) is built:
4492
4493 .. literalinclude::
4494 /../../tests/publishers/fixtures/postbuildscript003.yaml
4495 :language: yaml
4496 """
4497
4498 pbs_xml = XML.SubElement(
4499 xml_parent, "org.jenkinsci.plugins.postbuildscript.PostBuildScript"
4500 )
4501
4502 plugin_ver = registry.get_plugin_version("postbuildscript")
4503 if plugin_ver >= "2.0":
4504 pbs_xml = XML.SubElement(pbs_xml, "config")
4505
4506 mapping = [("mark-unstable-if-failed", "markBuildUnstable", False)]
4507 helpers.convert_mapping_to_xml(pbs_xml, data, mapping, fail_required=True)
4508
4509 if plugin_ver >= "2.0":
4510
4511 def add_execute_on(bs_data, result_xml):
4512 valid_values = ("matrix", "axes", "both")
4513 execute_on = bs_data.get("execute-on")
4514 if not execute_on:
4515 return
4516 if execute_on not in valid_values:
4517 raise JenkinsJobsException(
4518 "execute-on must be one of %s, got %s" % valid_values, execute_on
4519 )
4520 execute_on_xml = XML.SubElement(result_xml, "executeOn")
4521 execute_on_xml.text = execute_on.upper()
4522
4523 ################
4524 # Script Files #
4525 ################
4526
4527 script_mapping = [("role", "role", "BOTH"), ("file-path", "filePath", False)]
4528 sf_path = "org.jenkinsci.plugins.postbuildscript.model.ScriptFile"
4529 sf_xml = XML.SubElement(pbs_xml, "scriptFiles")
4530
4531 for gs_data in data.get("generic-script", []):
4532 x = XML.SubElement(sf_xml, sf_path)
4533 results_xml = XML.SubElement(x, "results")
4534
4535 for result in gs_data.get("build-on", ["SUCCESS"]):
4536 XML.SubElement(results_xml, "string").text = result
4537
4538 add_execute_on(gs_data, x)
4539
4540 helpers.convert_mapping_to_xml(
4541 x, gs_data, script_mapping, fail_required=True
4542 )
4543 XML.SubElement(x, "scriptType").text = "GENERIC"
4544
4545 for gs_data in data.get("groovy-script", []):
4546 x = XML.SubElement(sf_xml, sf_path)
4547 results_xml = XML.SubElement(x, "results")
4548
4549 for result in gs_data.get("build-on", ["SUCCESS"]):
4550 XML.SubElement(results_xml, "string").text = result
4551
4552 add_execute_on(gs_data, x)
4553
4554 helpers.convert_mapping_to_xml(
4555 x, gs_data, script_mapping, fail_required=True
4556 )
4557 XML.SubElement(x, "scriptType").text = "GROOVY"
4558
4559 #################
4560 # Inline Groovy #
4561 #################
4562
4563 groovy_mapping = [("role", "role", "BOTH"), ("content", "content", False)]
4564 gs_path = "org.jenkinsci.plugins.postbuildscript.model.Script"
4565 gs_xml = XML.SubElement(pbs_xml, "groovyScripts")
4566 for gs_data in data.get("groovy", []):
4567 x = XML.SubElement(gs_xml, gs_path)
4568 results_xml = XML.SubElement(x, "results")
4569
4570 for result in gs_data.get("build-on", ["SUCCESS"]):
4571 XML.SubElement(results_xml, "string").text = result
4572
4573 add_execute_on(gs_data, x)
4574
4575 helpers.convert_mapping_to_xml(
4576 x, gs_data, groovy_mapping, fail_required=True
4577 )
4578
4579 ############
4580 # Builders #
4581 ############
4582
4583 builder_mapping = [("role", "role", "BOTH")]
4584 bs_path = "org.jenkinsci.plugins.postbuildscript.model.PostBuildStep"
4585 bs_xml = XML.SubElement(pbs_xml, "buildSteps")
4586 for bs_data in data.get("builders", []):
4587 x = XML.SubElement(bs_xml, bs_path)
4588 results_xml = XML.SubElement(x, "results")
4589
4590 for result in bs_data.get("build-on", ["SUCCESS"]):
4591 XML.SubElement(results_xml, "string").text = result
4592
4593 add_execute_on(bs_data, x)
4594
4595 helpers.convert_mapping_to_xml(
4596 x, bs_data, builder_mapping, fail_required=True
4597 )
4598
4599 build_steps_xml = XML.SubElement(x, "buildSteps")
4600 for builder in bs_data.get("build-steps"):
4601 registry.dispatch("builder", build_steps_xml, builder)
4602
4603 else: # Options below are all deprecated in version < 2.0 of plugin
4604
4605 # Shell/Groovy in a file
4606 script_types = {
4607 "generic-script": "GenericScript",
4608 "groovy-script": "GroovyScriptFile",
4609 }
4610
4611 # Assuming yaml preserves order of input data make sure
4612 # corresponding XML steps are generated in the same order
4613 build_scripts = [
4614 (k, v)
4615 for k, v in data.items()
4616 if k in script_types or k in ["groovy", "builders"]
4617 ]
4618
4619 for step, script_data in build_scripts:
4620 if step in script_types:
4621 scripts_xml = XML.SubElement(
4622 pbs_xml, step[: -len("-script")] + "ScriptFileList"
4623 )
4624 for shell_script in script_data:
4625 script_xml = XML.SubElement(
4626 scripts_xml,
4627 "org.jenkinsci.plugins.postbuildscript." + script_types[step],
4628 )
4629 file_path_xml = XML.SubElement(script_xml, "filePath")
4630 file_path_xml.text = shell_script
4631
4632 # Inlined Groovy
4633 if step == "groovy":
4634 groovy_inline_xml = XML.SubElement(pbs_xml, "groovyScriptContentList")
4635 for groovy in script_data:
4636 groovy_xml = XML.SubElement(
4637 groovy_inline_xml,
4638 "org.jenkinsci.plugins.postbuildscript." "GroovyScriptContent",
4639 )
4640 groovy_content = XML.SubElement(groovy_xml, "content")
4641 groovy_content.text = groovy
4642
4643 # Inject builders
4644 if step == "builders":
4645 build_steps_xml = XML.SubElement(pbs_xml, "buildSteps")
4646 for builder in script_data:
4647 registry.dispatch("builder", build_steps_xml, builder)
4648
4649 # When to run the build? Note the plugin let one specify both options
4650 # although they are antinomic
4651 # onsuccess and onfailure parameters are deprecated, this is to keep
4652 # backwards compatability
4653 success_xml = XML.SubElement(pbs_xml, "scriptOnlyIfSuccess")
4654 if "script-only-if-succeeded" in data:
4655 success_xml.text = str(data.get("script-only-if-succeeded", True)).lower()
4656 else:
4657 success_xml.text = str(data.get("onsuccess", True)).lower()
4658
4659 failure_xml = XML.SubElement(pbs_xml, "scriptOnlyIfFailure")
4660 if "script-only-if-failed" in data:
4661 failure_xml.text = str(data.get("script-only-if-failed", False)).lower()
4662 else:
4663 failure_xml.text = str(data.get("onfailure", False)).lower()
4664
4665 # TODO: we may want to avoid setting "execute-on" on non-matrix jobs,
4666 # either by skipping this part or by raising an error to let the user
4667 # know an attempt was made to set execute-on on a non-matrix job.
4668 # There are currently no easy ways to check for this though.
4669 if "execute-on" in data:
4670 valid_values = ("matrix", "axes", "both")
4671 execute_on = data["execute-on"].lower()
4672 if execute_on not in valid_values:
4673 raise JenkinsJobsException(
4674 "execute-on must be one of %s, got %s" % valid_values, execute_on
4675 )
4676 execute_on_xml = XML.SubElement(pbs_xml, "executeOn")
4677 execute_on_xml.text = execute_on.upper()
4678
4679
4680 def xml_summary(registry, xml_parent, data):
4681 """yaml: xml-summary
4682 Adds support for the Summary Display Plugin
4683
4684 Requires the Jenkins :jenkins-plugins:`Summary Display Plugin
4685 <summary_report>`.
4686
4687 :arg str files: Files to parse (required)
4688 :arg bool shown-on-project-page: Display summary on project page
4689 (default false)
4690
4691 Minimal Example:
4692
4693 .. literalinclude::
4694 /../../tests/publishers/fixtures/xml-summary-minimal.yaml
4695 :language: yaml
4696
4697 Full Example:
4698
4699 .. literalinclude:: /../../tests/publishers/fixtures/xml-summary-full.yaml
4700 :language: yaml
4701 """
4702
4703 summary = XML.SubElement(
4704 xml_parent, "hudson.plugins.summary__report.ACIPluginPublisher"
4705 )
4706 summary.set("plugin", "summary_report")
4707
4708 mapping = [
4709 ("files", "name", None),
4710 ("shown-on-project-page", "shownOnProjectPage", False),
4711 ]
4712 helpers.convert_mapping_to_xml(summary, data, mapping, fail_required=True)
4713
4714
4715 def robot(registry, xml_parent, data):
4716 """yaml: robot
4717 Adds support for the Robot Framework Plugin
4718
4719 Requires the Jenkins :jenkins-plugins:`Robot Framework Plugin <robot>`.
4720
4721 :arg str output-path: Path to directory containing robot xml and html files
4722 relative to build workspace. (required)
4723 :arg str log-file-link: Name of log or report file to be linked on jobs
4724 front page (default '')
4725 :arg str report-html: Name of the html file containing robot test report
4726 (default 'report.html')
4727 :arg str log-html: Name of the html file containing detailed robot test log
4728 (default 'log.html')
4729 :arg str output-xml: Name of the xml file containing robot output
4730 (default 'output.xml')
4731 :arg str pass-threshold: Minimum percentage of passed tests to consider
4732 the build successful (default 0.0)
4733 :arg str unstable-threshold: Minimum percentage of passed test to
4734 consider the build as not failed (default 0.0)
4735 :arg bool only-critical: Take only critical tests into account when
4736 checking the thresholds (default true)
4737 :arg list other-files: list other files to archive (default '')
4738 :arg bool archive-output-xml: Archive output xml file to server
4739 (default true)
4740 :arg bool enable-cache: Enable cache for test results (default true)
4741
4742 Minimal Example:
4743
4744 .. literalinclude:: /../../tests/publishers/fixtures/robot-minimal.yaml
4745 :language: yaml
4746
4747 Full Example:
4748
4749 .. literalinclude:: /../../tests/publishers/fixtures/robot-full.yaml
4750 :language: yaml
4751 """
4752 parent = XML.SubElement(xml_parent, "hudson.plugins.robot.RobotPublisher")
4753 parent.set("plugin", "robot")
4754 mappings = [
4755 ("output-path", "outputPath", None),
4756 ("log-file-link", "logFileLink", ""),
4757 ("report-html", "reportFileName", "report.html"),
4758 ("log-html", "logFileName", "log.html"),
4759 ("output-xml", "outputFileName", "output.xml"),
4760 ("pass-threshold", "passThreshold", "0.0"),
4761 ("unstable-threshold", "unstableThreshold", "0.0"),
4762 ("only-critical", "onlyCritical", True),
4763 ("enable-cache", "enableCache", True),
4764 ]
4765 helpers.convert_mapping_to_xml(parent, data, mappings, fail_required=True)
4766
4767 other_files = XML.SubElement(parent, "otherFiles")
4768 for other_file in data.get("other-files", []):
4769 XML.SubElement(other_files, "string").text = str(other_file)
4770 XML.SubElement(parent, "disableArchiveOutput").text = str(
4771 not data.get("archive-output-xml", True)
4772 ).lower()
4773
4774
4775 def warnings(registry, xml_parent, data):
4776 """yaml: warnings
4777 Generate trend report for compiler warnings in the console log or
4778 in log files.
4779
4780 Requires the Jenkins Warnings Plugin
4781 (:jenkins-github:`warnings-plugin`).
4782
4783 :arg list console-log-parsers: The parser to use to scan the console
4784 log (default '')
4785 :arg dict workspace-file-scanners:
4786
4787 :workspace-file-scanners:
4788 * **file-pattern** (`str`) -- Fileset 'includes' setting that
4789 specifies the files to scan for warnings (required)
4790 * **scanner** (`str`) -- The parser to use to scan the files
4791 provided in workspace-file-pattern (default '')
4792 :arg str files-to-include: Comma separated list of regular
4793 expressions that specifies the files to include in the report
4794 (based on their absolute filename). By default all files are
4795 included
4796 :arg str files-to-ignore: Comma separated list of regular expressions
4797 that specifies the files to exclude from the report (based on their
4798 absolute filename). (default '')
4799 :arg str messages-to-ignore: Newline separated list of regular
4800 expressions that specifies the warning messages to exclude form the
4801 report (based on the warning messages). By default all warning
4802 messages are included
4803 :arg str categories-to-ignore: Newline separated list of regular
4804 expressions that specifies the warning messages to exclude form the
4805 report (based on the warning categories). By default all warning
4806 categories are included
4807 :arg bool run-always: By default, this plug-in runs only for stable or
4808 unstable builds, but not for failed builds. Set to true if the
4809 plug-in should run even for failed builds. (default false)
4810 :arg bool detect-modules: Determines if Ant or Maven modules should be
4811 detected for all files that contain warnings. Activating this
4812 option may increase your build time since the detector scans
4813 the whole workspace for 'build.xml' or 'pom.xml' files in order
4814 to assign the correct module names. (default false)
4815 :arg bool resolve-relative-paths: Determines if relative paths in
4816 warnings should be resolved using a time expensive operation that
4817 scans the whole workspace for matching files. Deactivate this
4818 option if you encounter performance problems. (default false)
4819 :arg int health-threshold-high: The upper threshold for the build
4820 health. If left empty then no health report is created. If
4821 the actual number of warnings is between the provided
4822 thresholds then the build health is interpolated (default '')
4823 :arg int health-threshold-low: The lower threshold for the build
4824 health. See health-threshold-high. (default '')
4825 :arg dict health-priorities: Determines which warning priorities
4826 should be considered when evaluating the build health (default
4827 all-priorities)
4828
4829 :health-priorities values:
4830 * **priority-high** -- Only priority high
4831 * **high-and-normal** -- Priorities high and normal
4832 * **all-priorities** -- All priorities
4833 :arg dict total-thresholds: If the number of total warnings is greater
4834 than one of these thresholds then a build is considered as unstable
4835 or failed, respectively. (default '')
4836
4837 :total-thresholds:
4838 * **unstable** (`dict`)
4839 :unstable: * **total-all** (`int`)
4840 * **total-high** (`int`)
4841 * **total-normal** (`int`)
4842 * **total-low** (`int`)
4843 * **failed** (`dict`)
4844 :failed: * **total-all** (`int`)
4845 * **total-high** (`int`)
4846 * **total-normal** (`int`)
4847 * **total-low** (`int`)
4848 :arg dict new-thresholds: If the specified number of new warnings exceeds
4849 one of these thresholds then a build is considered as unstable or
4850 failed, respectively. (default '')
4851
4852 :new-thresholds:
4853 * **unstable** (`dict`)
4854 :unstable: * **new-all** (`int`)
4855 * **new-high** (`int`)
4856 * **new-normal** (`int`)
4857 * **new-low** (`int`)
4858 * **failed** (`dict`)
4859 :failed: * **new-all** (`int`)
4860 * **new-high** (`int`)
4861 * **new-normal** (`int`)
4862 * **new-high** (`int`)
4863 :arg bool use-delta-for-new-warnings: If set then the number of new
4864 warnings is calculated by subtracting the total number of warnings
4865 of the current build from the reference build. This may lead to wrong
4866 results if you have both fixed and new warnings in a build. If not set,
4867 then the number of new warnings is calculated by an asymmetric set
4868 difference of the warnings in the current and reference build. This
4869 will find all new warnings even if the number of total warnings is
4870 decreasing. However, sometimes false positives will be reported due
4871 to minor changes in a warning (refactoring of variable of method
4872 names, etc.) (default false)
4873 :arg bool use-previous-build-as-reference: If set the number of new
4874 warnings will always be computed based on the previous build, even if
4875 that build is unstable (due to a violated warning threshold).
4876 Otherwise the last build that did not violate any given threshold will
4877 be used as
4878 reference. It is recommended to uncheck this option if the plug-in
4879 should ensure that all new warnings will be finally fixed in subsequent
4880 builds. (default false)
4881 :arg bool only-use-stable-builds-as-reference: The number of new warnings
4882 will be calculated based on the last stable build, allowing reverts
4883 of unstable builds where the number of warnings was decreased.
4884 (default false)
4885 :arg str default-encoding: Default encoding when parsing or showing files
4886 Leave empty to use default encoding of platform (default '')
4887
4888 Minimal Example:
4889
4890 .. literalinclude:: /../../tests/publishers/fixtures/warnings-minimal.yaml
4891 :language: yaml
4892
4893 Full Example:
4894
4895 .. literalinclude:: /../../tests/publishers/fixtures/warnings-full.yaml
4896 :language: yaml
4897 """
4898
4899 warnings = XML.SubElement(
4900 xml_parent, "hudson.plugins.warnings." "WarningsPublisher"
4901 )
4902 warnings.set("plugin", "warnings")
4903 console = XML.SubElement(warnings, "consoleParsers")
4904 for parser in data.get("console-log-parsers", []):
4905 console_parser = XML.SubElement(
4906 console, "hudson.plugins.warnings." "ConsoleParser"
4907 )
4908 XML.SubElement(console_parser, "parserName").text = parser
4909 workspace = XML.SubElement(warnings, "parserConfigurations")
4910 for wfs in data.get("workspace-file-scanners", []):
4911 workspace_pattern = XML.SubElement(
4912 workspace, "hudson.plugins.warnings." "ParserConfiguration"
4913 )
4914 workspace_pattern_mappings = [
4915 ("file-pattern", "pattern", None),
4916 ("scanner", "parserName", ""),
4917 ]
4918 helpers.convert_mapping_to_xml(
4919 workspace_pattern, wfs, workspace_pattern_mappings, fail_required=True
4920 )
4921 prioritiesDict = {
4922 "priority-high": "high",
4923 "high-and-normal": "normal",
4924 "all-priorities": "low",
4925 }
4926 warnings_mappings = [
4927 ("files-to-include", "includePattern", ""),
4928 ("files-to-ignore", "excludePattern", ""),
4929 ("messages-to-ignore", "messagesPattern", ""),
4930 ("categories-to-ignore", "categoriesPattern", ""),
4931 ("plugin-name", "pluginName", "[WARNINGS]"),
4932 ("run-always", "canRunOnFailed", False),
4933 ("detect-modules", "shouldDetectModules", False),
4934 ("health-threshold-high", "healthy", ""),
4935 ("health-threshold-low", "unHealthy", ""),
4936 ("health-priorities", "thresholdLimit", "all-priorities", prioritiesDict),
4937 ("default-encoding", "defaultEncoding", ""),
4938 ]
4939 helpers.convert_mapping_to_xml(
4940 warnings, data, warnings_mappings, fail_required=True
4941 )
4942 # Note the logic reversal (included here to match the GUI)
4943 XML.SubElement(warnings, "doNotResolveRelativePaths").text = str(
4944 not data.get("resolve-relative-paths", False)
4945 ).lower()
4946 td = XML.SubElement(warnings, "thresholds")
4947 for base in ["total", "new"]:
4948 thresholds = data.get("%s-thresholds" % base, {})
4949 for status in ["unstable", "failed"]:
4950 bystatus = thresholds.get(status, {})
4951 for level in ["all", "high", "normal", "low"]:
4952 val = str(bystatus.get("%s-%s" % (base, level), ""))
4953 XML.SubElement(
4954 td, "%s%s%s" % (status, base.capitalize(), level.capitalize())
4955 ).text = val
4956 if data.get("new-thresholds"):
4957 XML.SubElement(warnings, "dontComputeNew").text = "false"
4958 delta = data.get("use-delta-for-new-warnings", False)
4959 XML.SubElement(warnings, "useDeltaValues").text = str(delta).lower()
4960 use_previous_build = data.get("use-previous-build-as-reference", False)
4961 XML.SubElement(warnings, "usePreviousBuildAsReference").text = str(
4962 use_previous_build
4963 ).lower()
4964 use_stable_builds = data.get("only-use-stable-builds-as-reference", False)
4965 XML.SubElement(warnings, "useStableBuildAsReference").text = str(
4966 use_stable_builds
4967 ).lower()
4968 else:
4969 XML.SubElement(warnings, "dontComputeNew").text = "true"
4970 XML.SubElement(warnings, "useDeltaValues").text = "false"
4971 XML.SubElement(warnings, "usePreviousBuildAsReference").text = "false"
4972 XML.SubElement(warnings, "useStableBuildAsReference").text = "false"
4973
4974
4975 def sloccount(registry, xml_parent, data):
4976 r"""yaml: sloccount
4977 Generates the trend report for SLOCCount
4978
4979 Requires the Jenkins :jenkins-plugins:`SLOCCount Plugin <sloccount>`.
4980
4981 :arg str report-files: Setting that specifies the generated raw
4982 SLOCCount report files. Be sure not to include any non-report files
4983 into this pattern. The report files must have been generated by
4984 sloccount using the "--wide --details" options.
4985 (default '\*\*/sloccount.sc')
4986 :arg str charset: The character encoding to be used to read the SLOCCount
4987 result files. (default 'UTF-8')
4988 :arg int builds-in-graph: Maximal number of last successful builds, that
4989 are displayed in the trend graphs. (default 0)
4990 :arg bool comment-is-code: This option is considered only in the cloc
4991 report parser and is ignored in the SLOCCount one. (default false)
4992 :arg bool ignore-build-failure: Try to process the report files even if
4993 the build is not successful. (default false)
4994
4995 Minimal Example:
4996
4997 .. literalinclude:: /../../tests/publishers/fixtures/sloccount-minimal.yaml
4998 :language: yaml
4999
5000 Full Example:
5001
5002 .. literalinclude::
5003 /../../tests/publishers/fixtures/sloccount-full.yaml
5004 :language: yaml
5005 """
5006 top = XML.SubElement(xml_parent, "hudson.plugins.sloccount.SloccountPublisher")
5007 top.set("plugin", "sloccount")
5008 mappings = [
5009 ("report-files", "pattern", "**/sloccount.sc"),
5010 ("charset", "encoding", "UTF-8"),
5011 ("builds-in-graph", "numBuildsInGraph", 0),
5012 ("comment-is-code", "commentIsCode", False),
5013 ("ignore-build-failure", "ignoreBuildFailure", False),
5014 ]
5015 helpers.convert_mapping_to_xml(top, data, mappings, fail_required=True)
5016
5017
5018 def ircbot(registry, xml_parent, data):
5019 """yaml: ircbot
5020 ircbot enables Jenkins to send build notifications via IRC and lets you
5021 interact with Jenkins via an IRC bot.
5022
5023 Requires the Jenkins :jenkins-plugins:`IRC Plugin <ircbot>`.
5024
5025 :arg str strategy: When to send notifications
5026
5027 :strategy values:
5028 * **all** always (default)
5029 * **any-failure** on any failure
5030 * **failure-and-fixed** on failure and fixes
5031 * **new-failure-and-fixed** on new failure and fixes
5032 * **statechange-only** only on state change
5033 :arg bool notify-start: Whether to send notifications to channels when a
5034 build starts (default false)
5035 :arg bool notify-committers: Whether to send notifications to the users
5036 that are suspected of having broken this build (default false)
5037 :arg bool notify-culprits: Also send notifications to 'culprits' from
5038 previous unstable/failed builds (default false)
5039 :arg bool notify-upstream: Whether to send notifications to upstream
5040 committers if no committers were found for a broken build
5041 (default false)
5042 :arg bool notify-fixers: Whether to send notifications to the users that
5043 have fixed a broken build (default false)
5044 :arg str message-type: Channel Notification Message.
5045
5046 :message-type values:
5047 * **summary-scm** for summary and SCM changes (default)
5048 * **summary** for summary only
5049 * **summary-params** for summary and build parameters
5050 * **summary-scm-fail** for summary, SCM changes, failures)
5051 :arg list channels: list channels definitions
5052 If empty, it takes channel from Jenkins configuration.
5053 (default empty)
5054 WARNING: the IRC plugin requires the channel to be configured in the
5055 system wide configuration or the jobs will fail to emit notifications
5056 to the channel
5057
5058 :Channel: * **name** (`str`) Channel name
5059 * **password** (`str`) Channel password (optional)
5060 * **notify-only** (`bool`) Set to true if you want to
5061 disallow bot commands (default false)
5062 :arg str matrix-notifier: notify for matrix projects
5063 instant-messaging-plugin injects an additional
5064 field in the configuration form whenever the
5065 project is a multi-configuration project
5066
5067 :matrix-notifier values:
5068 * **all**
5069 * **only-configurations** (default)
5070 * **only-parent**
5071
5072 Minimal Example:
5073
5074 .. literalinclude:: /../../tests/publishers/fixtures/ircbot-minimal.yaml
5075 :language: yaml
5076
5077 Full Example:
5078
5079 .. literalinclude:: /../../tests/publishers/fixtures/ircbot-full.yaml
5080 :language: yaml
5081 """
5082 top = XML.SubElement(xml_parent, "hudson.plugins.ircbot.IrcPublisher")
5083 top.set("plugin", "ircbot")
5084 message_dict = {
5085 "summary-scm": "DefaultBuildToChatNotifier",
5086 "summary": "SummaryOnlyBuildToChatNotifier",
5087 "summary-params": "BuildParametersBuildToChatNotifier",
5088 "summary-scm-fail": "PrintFailingTestsBuildToChatNotifier",
5089 }
5090 message = data.get("message-type", "summary-scm")
5091 if message not in message_dict:
5092 raise JenkinsJobsException(
5093 "message-type entered is not valid, must "
5094 "be one of: %s" % ", ".join(message_dict.keys())
5095 )
5096 message = "hudson.plugins.im.build_notify." + message_dict.get(message)
5097 XML.SubElement(top, "buildToChatNotifier", attrib={"class": message})
5098 targets = XML.SubElement(top, "targets")
5099 channels = data.get("channels", [])
5100 for channel in channels:
5101 sub = XML.SubElement(targets, "hudson.plugins.im.GroupChatIMMessageTarget")
5102 sub_mappings = [
5103 ("name", "name", ""),
5104 ("password", "password", ""),
5105 ("notify-only", "notificationOnly", False),
5106 ]
5107 helpers.convert_mapping_to_xml(sub, channel, sub_mappings, fail_required=True)
5108 strategy_dict = {
5109 "all": "ALL",
5110 "any-failure": "ANY_FAILURE",
5111 "failure-and-fixed": "FAILURE_AND_FIXED",
5112 "new-failure-and-fixed": "NEW_FAILURE_AND_FIXED",
5113 "statechange-only": "STATECHANGE_ONLY",
5114 }
5115 matrix_dict = {
5116 "all": "ALL",
5117 "only-configurations": "ONLY_CONFIGURATIONS",
5118 "only-parent": "ONLY_PARENT",
5119 }
5120 mappings = [
5121 ("strategy", "strategy", "all", strategy_dict),
5122 ("notify-start", "notifyOnBuildStart", False),
5123 ("notify-committers", "notifySuspects", False),
5124 ("notify-culprits", "notifyCulprits", False),
5125 ("notify-fixers", "notifyFixers", False),
5126 ("notify-upstream", "notifyUpstreamCommitters", False),
5127 ("matrix-notifier", "matrixMultiplier", "only-configurations", matrix_dict),
5128 ]
5129 helpers.convert_mapping_to_xml(top, data, mappings, fail_required=True)
5130
5131
5132 def plot(registry, xml_parent, data):
5133 """yaml: plot
5134 Plot provides generic plotting (or graphing).
5135
5136 Requires the Jenkins :jenkins-plugins:`Plot Plugin <plot>`.
5137
5138 :arg str title: title for the graph (default '')
5139 :arg str yaxis: title of Y axis (default '')
5140 :arg int width: the width of the plot in pixels (default 750)
5141 :arg int height: the height of the plot in pixels (default 450)
5142 :arg str group: name of the group to which the plot belongs (required)
5143 :arg int num-builds: number of builds to plot across
5144 (default plot all builds)
5145 :arg str style: Specifies the graph style of the plot
5146 Can be: area, bar, bar3d, line, line3d, stackedArea, stackedbar,
5147 stackedbar3d, waterfall (default 'line')
5148 :arg bool use-description: When false, the X-axis labels are formed using
5149 build numbers and dates, and the corresponding tooltips contain the
5150 build descriptions. When enabled, the contents of the labels and
5151 tooltips are swapped, with the descriptions used as X-axis labels and
5152 the build number and date used for tooltips. (default false)
5153 :arg bool exclude-zero-yaxis: When false, Y-axis contains the value zero
5154 even if it is not included in the data series. When true, the value
5155 zero is not automatically included. (default false)
5156 :arg bool logarithmic-yaxis: When true, the Y-axis will use a logarithmic
5157 scale. By default, the Y-axis uses a linear scale. (default false)
5158 :arg bool keep-records: When true, show all builds up to 'Number of
5159 builds to include'. (default false)
5160 :arg str csv-file-name: Use for choosing the file name in which the data
5161 will be persisted. If none specified and random name is generated as
5162 done in the Jenkins Plot plugin. (default random generated .csv
5163 filename, same behaviour as the Jenkins Plot plugin)
5164 :arg list series: list data series definitions
5165
5166 :Series: * **file** (`str`) : files to include
5167 * **inclusion-flag** filtering mode for CSV files. Possible
5168 values are:
5169
5170 * **off** (default)
5171 * **include-by-string**
5172 * **exclude-by-string**
5173 * **include-by-column**
5174 * **exclude-by-column**
5175
5176 * **exclude** (`str`) : exclude pattern for CSV file.
5177 * **url** (`str`) : for 'csv' and 'xml' file types
5178 used when you click on a point (default empty)
5179 * **display-table** (`bool`) : for 'csv' file type
5180 if true, original CSV will be shown above plot (default false)
5181 * **label** (`str`) : used by 'properties' file type
5182 Specifies the legend label for this data series.
5183 (default empty)
5184 * **format** (`str`) : Type of file where we get datas.
5185 Can be: properties, csv, xml
5186 * **xpath-type** (`str`) : The result type of the expression must
5187 be supplied due to limitations in the java.xml.xpath parsing.
5188 The result can be: node, nodeset, boolean, string, or number.
5189 Strings and numbers will be converted to double. Boolean will
5190 be converted to 1 for true, and 0 for false. (default 'node')
5191 * **xpath** (`str`) : used by 'xml' file type
5192 Xpath which selects the values that should be plotted.
5193
5194
5195 Minimal Example:
5196
5197 .. literalinclude:: /../../tests/publishers/fixtures/plot-minimal.yaml
5198 :language: yaml
5199
5200 Full Example:
5201
5202 .. literalinclude:: /../../tests/publishers/fixtures/plot-full.yaml
5203 :language: yaml
5204 """
5205 top = XML.SubElement(xml_parent, "hudson.plugins.plot.PlotPublisher")
5206 plots = XML.SubElement(top, "plots")
5207 format_dict = {
5208 "properties": "hudson.plugins.plot.PropertiesSeries",
5209 "csv": "hudson.plugins.plot.CSVSeries",
5210 "xml": "hudson.plugins.plot.XMLSeries",
5211 }
5212 xpath_dict = {
5213 "nodeset": "NODESET",
5214 "node": "NODE",
5215 "string": "STRING",
5216 "boolean": "BOOLEAN",
5217 "number": "NUMBER",
5218 }
5219 inclusion_dict = {
5220 "off": "OFF",
5221 "include-by-string": "INCLUDE_BY_STRING",
5222 "exclude-by-string": "EXCLUDE_BY_STRING",
5223 "include-by-column": "INCLUDE_BY_COLUMN",
5224 "exclude-by-column": "EXCLUDE_BY_COLUMN",
5225 }
5226
5227 style_list = [
5228 "area",
5229 "bar",
5230 "bar3d",
5231 "line",
5232 "line3d",
5233 "stackedArea",
5234 "stackedbar",
5235 "stackedbar3d",
5236 "waterfall",
5237 ]
5238
5239 plot_mappings = [
5240 ("title", "title", ""),
5241 ("yaxis", "yaxis", ""),
5242 ("width", "width", "750"),
5243 ("height", "height", "450"),
5244 ("csv-file-name", "csvFileName", ""),
5245 ("group", "group", None),
5246 ("use-description", "useDescr", False),
5247 ("exclude-zero-yaxis", "exclZero", False),
5248 ("logarithmic-yaxis", "logarithmic", False),
5249 ("keep-records", "keepRecords", False),
5250 ("num-builds", "numBuilds", ""),
5251 ("style", "style", "line", style_list),
5252 ]
5253
5254 plot_csv_mappings = [
5255 ("inclusion-flag", "inclusionFlag", "off", inclusion_dict),
5256 ("exclude", "exclusionValues", ""),
5257 ("url", "url", ""),
5258 ("display-table", "displayTableFlag", False),
5259 ]
5260
5261 plot_xml_mappings = [
5262 ("url", "url", ""),
5263 ("xpath", "xpathString", ""),
5264 ("xpath-type", "nodeTypeString", "node", xpath_dict),
5265 ]
5266
5267 for plot in data:
5268 plugin = XML.SubElement(plots, "hudson.plugins.plot.Plot")
5269 helpers.convert_mapping_to_xml(plugin, plot, plot_mappings, fail_required=True)
5270
5271 topseries = XML.SubElement(plugin, "series")
5272 series = plot["series"]
5273 for serie in series:
5274 format_data = serie.get("format")
5275 if format_data not in format_dict:
5276 raise JenkinsJobsException(
5277 "format entered is not valid, must "
5278 "be one of: %s" % " , ".join(format_dict.keys())
5279 )
5280 subserie = XML.SubElement(topseries, format_dict.get(format_data))
5281 XML.SubElement(subserie, "file").text = serie.get("file")
5282 if format_data == "properties":
5283 XML.SubElement(subserie, "label").text = serie.get("label", "")
5284 if format_data == "csv":
5285 helpers.convert_mapping_to_xml(
5286 subserie, serie, plot_csv_mappings, fail_required=True
5287 )
5288 if serie.get("exclude", ""):
5289 exclude_strings = serie.get("exclude", "").split(",")
5290 exclusionset = XML.SubElement(subserie, "strExclusionSet")
5291 for exclude_string in exclude_strings:
5292 XML.SubElement(exclusionset, "string").text = exclude_string
5293 if format_data == "xml":
5294 helpers.convert_mapping_to_xml(
5295 subserie, serie, plot_xml_mappings, fail_required=True
5296 )
5297 XML.SubElement(subserie, "fileType").text = serie.get("format")
5298
5299
5300 def git(registry, xml_parent, data):
5301 """yaml: git
5302 This plugin will configure the Jenkins Git plugin to
5303 push merge results, tags, and/or branches to
5304 remote repositories after the job completes.
5305
5306 Requires the Jenkins :jenkins-plugins:`Git Plugin <git>`.
5307
5308 :arg bool push-merge: push merges back to the origin specified in the
5309 pre-build merge options (default false)
5310 :arg bool push-only-if-success: Only push to remotes if the build succeeds
5311 - otherwise, nothing will be pushed.
5312 (default true)
5313 :arg bool force-push: Add force option to git push (default false)
5314 :arg list tags: tags to push at the completion of the build
5315
5316 :tag: * **remote** (`str`) remote repo name to push to
5317 (default 'origin')
5318 * **name** (`str`) name of tag to push
5319 * **message** (`str`) message content of the tag
5320 * **create-tag** (`bool`) whether or not to create the tag
5321 after the build, if this is False then the tag needs to
5322 exist locally (default false)
5323 * **update-tag** (`bool`) whether to overwrite a remote tag
5324 or not (default false)
5325
5326 :arg list branches: branches to push at the completion of the build
5327
5328 :branch: * **remote** (`str`) remote repo name to push to
5329 (default 'origin')
5330 * **name** (`str`) name of remote branch to push to
5331 * **rebase** (`bool`) whether or not to rebase before push
5332 (default false)
5333
5334 :arg list notes: notes to push at the completion of the build
5335
5336 :note: * **remote** (`str`) remote repo name to push to
5337 (default 'origin')
5338 * **message** (`str`) content of the note
5339 * **namespace** (`str`) namespace of the note
5340 (default master)
5341 * **replace-note** (`bool`) whether to overwrite a note or not
5342 (default false)
5343
5344
5345 Minimal Example:
5346
5347 .. literalinclude:: /../../tests/publishers/fixtures/git-minimal.yaml
5348 :language: yaml
5349
5350 Full Example:
5351
5352 .. literalinclude:: /../../tests/publishers/fixtures/git-full.yaml
5353 :language: yaml
5354 """
5355 mappings = [
5356 ("push-merge", "pushMerge", False),
5357 ("push-only-if-success", "pushOnlyIfSuccess", True),
5358 ("force-push", "forcePush", False),
5359 ]
5360
5361 tag_mappings = [
5362 ("remote", "targetRepoName", "origin"),
5363 ("name", "tagName", None),
5364 ("message", "tagMessage", ""),
5365 ("create-tag", "createTag", False),
5366 ("update-tag", "updateTag", False),
5367 ]
5368
5369 branch_mappings = [
5370 ("remote", "targetRepoName", "origin"),
5371 ("name", "branchName", None),
5372 ("rebase", "rebaseBeforePush", False),
5373 ]
5374
5375 note_mappings = [
5376 ("remote", "targetRepoName", "origin"),
5377 ("message", "noteMsg", None),
5378 ("namespace", "noteNamespace", "master"),
5379 ("replace-note", "noteReplace", False),
5380 ]
5381
5382 top = XML.SubElement(xml_parent, "hudson.plugins.git.GitPublisher")
5383 XML.SubElement(top, "configVersion").text = "2"
5384 helpers.convert_mapping_to_xml(top, data, mappings, fail_required=True)
5385
5386 tags = data.get("tags", [])
5387 if tags:
5388 xml_tags = XML.SubElement(top, "tagsToPush")
5389 for tag in tags:
5390 xml_tag = XML.SubElement(
5391 xml_tags, "hudson.plugins.git.GitPublisher_-TagToPush"
5392 )
5393 helpers.convert_mapping_to_xml(
5394 xml_tag, tag["tag"], tag_mappings, fail_required=True
5395 )
5396
5397 branches = data.get("branches", [])
5398 if branches:
5399 xml_branches = XML.SubElement(top, "branchesToPush")
5400 for branch in branches:
5401 xml_branch = XML.SubElement(
5402 xml_branches, "hudson.plugins.git.GitPublisher_-BranchToPush"
5403 )
5404 helpers.convert_mapping_to_xml(
5405 xml_branch, branch["branch"], branch_mappings, fail_required=True
5406 )
5407
5408 notes = data.get("notes", [])
5409 if notes:
5410 xml_notes = XML.SubElement(top, "notesToPush")
5411 for note in notes:
5412 xml_note = XML.SubElement(
5413 xml_notes, "hudson.plugins.git.GitPublisher_-NoteToPush"
5414 )
5415 helpers.convert_mapping_to_xml(
5416 xml_note, note["note"], note_mappings, fail_required=True
5417 )
5418
5419
5420 def github_notifier(registry, xml_parent, data):
5421 """yaml: github-notifier
5422 Set build status on Github commit.
5423 Requires the Jenkins :jenkins-plugins:`Github Plugin <github>`.
5424
5425 Example:
5426
5427 .. literalinclude:: /../../tests/publishers/fixtures/github-notifier.yaml
5428 :language: yaml
5429 """
5430 XML.SubElement(xml_parent, "com.cloudbees.jenkins.GitHubCommitNotifier")
5431
5432
5433 def gitlab_notifier(registry, xml_parent, data):
5434 """yaml: gitlab-notifier
5435 Set build status on GitLab commit.
5436 Requires the Jenkins :jenkins-plugins:`GitLab Plugin <gitlab-plugin>`.
5437
5438 :arg str name: The name of the build in GitLab. With this you can
5439 distinguish different Jenkins jobs for the same commit in GitLab.
5440 (default 'jenkins')
5441 :arg bool mark-unstable-as-success: (default false)
5442
5443 Minimal Example:
5444
5445 .. literalinclude::
5446 /../../tests/publishers/fixtures/gitlab-notifier-minimal.yaml
5447 :language: yaml
5448
5449 Full Example:
5450
5451 .. literalinclude::
5452 /../../tests/publishers/fixtures/gitlab-notifier-full.yaml
5453 :language: yaml
5454 """
5455 top = XML.SubElement(
5456 xml_parent, "com.dabsquared.gitlabjenkins.publisher.GitLabCommitStatusPublisher"
5457 )
5458 top.set("plugin", "gitlab-plugin")
5459
5460 mappings = [
5461 ("name", "name", "jenkins"),
5462 ("mark-unstable-as-success", "markUnstableAsSuccess", False),
5463 ]
5464 helpers.convert_mapping_to_xml(top, data, mappings, fail_required=True)
5465
5466
5467 def gitlab_vote(registry, xml_parent, data):
5468 """yaml: gitlab-vote
5469 Set vote for build status on GitLab merge request.
5470 Requires the Jenkins :jenkins-plugins:`GitLab Plugin <gitlab-plugin>`.
5471
5472 Example:
5473
5474 .. literalinclude::
5475 ../../tests/publishers/fixtures/gitlab-vote.yaml
5476 :language: yaml
5477 """
5478 XML.SubElement(
5479 xml_parent, "com.dabsquared.gitlabjenkins.publisher.GitLabVotePublisher"
5480 )
5481
5482
5483 def gitlab_message(registry, xml_parent, data):
5484 """yaml: gitlab-message
5485 Add note with build status on GitLab merge request.
5486 Requires the Jenkins :jenkins-plugins:`GitLab Plugin <gitlab-plugin>`.
5487
5488 :arg bool failure-only: make a comment only on failure (default false)
5489 :arg bool success-note: make a comment on GitLab Merge Request
5490 if build succeeds (default false)
5491 :arg bool failure-note: make a comment on GitLab Merge Request
5492 if build failed (default false)
5493 :arg bool abort-note: make a comment on GitLab Merge Request
5494 if build aborted (default false)
5495 :arg bool unstable-note: make a comment on GitLab Merge Request
5496 if build unstable (default false)
5497
5498 :arg str success-note-text: text of comment on success build (default '')
5499 :arg str failure-note-text: text of comment on failed build (default '')
5500 :arg str abort-note-text: text of comment on aborted build (default '')
5501 :arg str unstable-note-text: text of comment on unstable build (default '')
5502
5503 Minimal Example:
5504
5505 .. literalinclude::
5506 /../../tests/publishers/fixtures/gitlab-message-minimal.yaml
5507 :language: yaml
5508
5509 Full Example:
5510
5511 .. literalinclude::
5512 /../../tests/publishers/fixtures/gitlab-message-full.yaml
5513 :language: yaml
5514 """
5515 gitlab = XML.SubElement(
5516 xml_parent, "com.dabsquared.gitlabjenkins.publisher.GitLabMessagePublisher"
5517 )
5518 gitlab.set("plugin", "gitlab-plugin")
5519
5520 mapping = [
5521 ("failure-only", "onlyForFailure", False),
5522 ("success-note", "replaceSuccessNote", False),
5523 ("failure-note", "replaceFailureNote", False),
5524 ("abort-note", "replaceAbortNote", False),
5525 ("unstable-note", "replaceUnstableNote", False),
5526 ("success-note-text", "successNoteText", ""),
5527 ("failure-note-text", "failureNoteText", ""),
5528 ("abort-note-text", "abortNoteText", ""),
5529 ("unstable-note-text", "unstableNoteText", ""),
5530 ]
5531
5532 helpers.convert_mapping_to_xml(gitlab, data, mapping, fail_required=True)
5533
5534
5535 def zulip(registry, xml_parent, data):
5536 """yaml: zulip
5537 Set build status on zulip.
5538 Requires the Jenkins :jenkins-plugins:`Humbug Plugin <humbug>`.
5539
5540 Example:
5541
5542 .. literalinclude:: /../../tests/publishers/fixtures/zulip.yaml
5543 :language: yaml
5544 """
5545 XML.SubElement(xml_parent, "hudson.plugins.humbug.HumbugNotifier")
5546
5547
5548 def build_publisher(registry, xml_parent, data):
5549 """yaml: build-publisher
5550 This plugin allows records from one Jenkins to be published
5551 on another Jenkins.
5552
5553 Requires the Jenkins :jenkins-plugins:`Build Publisher Plugin
5554 <build-publisher>`.
5555
5556 :arg bool publish-unstable-builds: publish unstable builds (default true)
5557 :arg bool publish-failed-builds: publish failed builds (default true)
5558 :arg int days-to-keep: days to keep when publishing results (optional)
5559 :arg int num-to-keep: number of jobs to keep in the published results
5560 (optional)
5561
5562 Minimal Example:
5563
5564 .. literalinclude::
5565 /../../tests/publishers/fixtures/build-publisher-minimal.yaml
5566 :language: yaml
5567
5568 Full Example:
5569
5570 .. literalinclude::
5571 /../../tests/publishers/fixtures/build-publisher-full.yaml
5572 :language: yaml
5573 """
5574
5575 reporter = XML.SubElement(
5576 xml_parent, "hudson.plugins.build__publisher.BuildPublisher"
5577 )
5578
5579 mappings = [
5580 ("publish-unstable-builds", "publishUnstableBuilds", True),
5581 ("publish-failed-builds", "publishFailedBuilds", True),
5582 ]
5583 helpers.convert_mapping_to_xml(reporter, data, mappings, fail_required=True)
5584 if "days-to-keep" in data or "num-to-keep" in data:
5585 logrotator = XML.SubElement(reporter, "logRotator")
5586 mappings = [
5587 ("days-to-keep", "daysToKeep", -1),
5588 ("num-to-keep", "numToKeep", -1),
5589 # hardcoded to -1 to emulate what the build publisher
5590 # plugin seem to do.
5591 ("", "artifactDaysToKeep", -1),
5592 ("", "artifactNumToKeep", -1),
5593 ]
5594 helpers.convert_mapping_to_xml(logrotator, data, mappings, fail_required=True)
5595
5596
5597 def stash(registry, xml_parent, data):
5598 """yaml: stash
5599 This plugin will configure the Jenkins BitBucket Server Notifier plugin to
5600 notify Atlassian BitBucket after job completes.
5601
5602 Requires the Jenkins :jenkins-plugins:`Bitbucket Server Notifier Plugin
5603 <stashNotifier>`.
5604
5605 :arg str url: Base url of Stash Server (default "")
5606 :arg str username: Username of Stash Server (default "")
5607 :arg str password: Password of Stash Server (default "")
5608 :arg str credentials-id: Credentials of Stash Server (optional)
5609 :arg bool ignore-ssl: Ignore unverified SSL certificate (default false)
5610 :arg str commit-sha1: Commit SHA1 to notify (default "")
5611 :arg bool include-build-number: Include build number in key
5612 (default false)
5613
5614 Minimal Example:
5615
5616 .. literalinclude:: /../../tests/publishers/fixtures/stash-minimal.yaml
5617 :language: yaml
5618
5619 Full Example:
5620
5621 .. literalinclude:: /../../tests/publishers/fixtures/stash-full.yaml
5622 :language: yaml
5623 """
5624 top = XML.SubElement(
5625 xml_parent, "org.jenkinsci.plugins.stashNotifier.StashNotifier"
5626 )
5627
5628 XML.SubElement(top, "stashServerBaseUrl").text = data.get("url", "")
5629 if data.get("credentials-id") is not None:
5630 XML.SubElement(top, "credentialsId").text = str(data.get("credentials-id"))
5631 else:
5632 XML.SubElement(
5633 top, "stashUserName"
5634 ).text = helpers.get_value_from_yaml_or_config_file(
5635 "username", "stash", data, registry.jjb_config
5636 )
5637 XML.SubElement(
5638 top, "stashUserPassword"
5639 ).text = helpers.get_value_from_yaml_or_config_file(
5640 "password", "stash", data, registry.jjb_config
5641 )
5642 mappings = [
5643 ("ignore-ssl", "ignoreUnverifiedSSLPeer", False),
5644 ("commit-sha1", "commitSha1", ""),
5645 ("include-build-number", "includeBuildNumberInKey", False),
5646 ]
5647 helpers.convert_mapping_to_xml(top, data, mappings, fail_required=True)
5648
5649
5650 def dependency_check(registry, xml_parent, data):
5651 """yaml: dependency-check
5652 Dependency-Check is an open source utility that identifies project
5653 dependencies and checks if there are any known, publicly disclosed,
5654 vulnerabilities.
5655
5656 Requires the Jenkins :jenkins-plugins:`OWASP Dependency-Check Plugin
5657 <dependency-check-jenkins-plugin>`.
5658
5659 :arg str pattern: Report filename pattern (optional)
5660 :arg bool can-run-on-failed: Also runs for failed builds, instead of just
5661 stable or unstable builds (default false)
5662 :arg bool should-detect-modules: Determines if Ant or Maven modules should
5663 be detected for all files that contain warnings (default false)
5664 :arg int healthy: Sunny threshold (optional)
5665 :arg int unhealthy: Stormy threshold (optional)
5666 :arg str health-threshold: Threshold priority for health status
5667 ('low', 'normal' or 'high', defaulted to 'low')
5668 :arg dict thresholds: Mark build as failed or unstable if the number of
5669 errors exceeds a threshold. (optional)
5670
5671 :thresholds:
5672 * **unstable** (`dict`)
5673 :unstable: * **total-all** (`int`)
5674 * **total-high** (`int`)
5675 * **total-normal** (`int`)
5676 * **total-low** (`int`)
5677 * **new-all** (`int`)
5678 * **new-high** (`int`)
5679 * **new-normal** (`int`)
5680 * **new-low** (`int`)
5681
5682 * **failed** (`dict`)
5683 :failed: * **total-all** (`int`)
5684 * **total-high** (`int`)
5685 * **total-normal** (`int`)
5686 * **total-low** (`int`)
5687 * **new-all** (`int`)
5688 * **new-high** (`int`)
5689 * **new-normal** (`int`)
5690 * **new-low** (`int`)
5691 :arg str default-encoding: Encoding for parsing or showing files (optional)
5692 :arg bool do-not-resolve-relative-paths: (default false)
5693 :arg bool dont-compute-new: If set to false, computes new warnings based on
5694 the reference build (default true)
5695 :arg bool use-previous-build-as-reference: determines whether to always
5696 use the previous build as the reference build (default false)
5697 :arg bool use-stable-build-as-reference: The number of new warnings will be
5698 calculated based on the last stable build, allowing reverts of unstable
5699 builds where the number of warnings was decreased. (default false)
5700 :arg bool use-delta-values: If set then the number of new warnings is
5701 calculated by subtracting the total number of warnings of the current
5702 build from the reference build.
5703 (default false)
5704
5705 Minimal Example:
5706
5707 .. literalinclude::
5708 /../../tests/publishers/fixtures/dependency-check-minimal.yaml
5709 :language: yaml
5710
5711 Full Example:
5712
5713 .. literalinclude::
5714 /../../tests/publishers/fixtures/dependency-check-full.yaml
5715 :language: yaml
5716 """
5717
5718 dependency_check = XML.SubElement(
5719 xml_parent, "org.jenkinsci.plugins.DependencyCheck.DependencyCheckPublisher"
5720 )
5721
5722 # trends
5723 helpers.build_trends_publisher("[DEPENDENCYCHECK] ", dependency_check, data)
5724
5725
5726 def description_setter(registry, xml_parent, data):
5727 """yaml: description-setter
5728 This plugin sets the description for each build,
5729 based upon a RegEx test of the build log file.
5730
5731 Requires the Jenkins :jenkins-plugins:`Description Setter Plugin
5732 <description-setter>`.
5733
5734 :arg str regexp: A RegEx which is used to scan the build log file
5735 (default '')
5736 :arg str regexp-for-failed: A RegEx which is used for failed builds
5737 (default '')
5738 :arg str description: The description to set on the build (optional)
5739 :arg str description-for-failed: The description to set on
5740 the failed builds (optional)
5741 :arg bool set-for-matrix: Also set the description on
5742 a multi-configuration build (default false)
5743
5744 Minimal Example:
5745
5746 .. literalinclude::
5747 /../../tests/publishers/fixtures/description-setter-minimal.yaml
5748 :language: yaml
5749
5750 Full Example:
5751
5752 .. literalinclude::
5753 /../../tests/publishers/fixtures/description-setter-full.yaml
5754 :language: yaml
5755 """
5756
5757 descriptionsetter = XML.SubElement(
5758 xml_parent, "hudson.plugins.descriptionsetter.DescriptionSetterPublisher"
5759 )
5760 mappings = [
5761 ("regexp", "regexp", ""),
5762 ("regexp-for-failed", "regexpForFailed", ""),
5763 ("description", "description", None),
5764 ("description-for-failed", "descriptionForFailed", None),
5765 ("set-for-matrix", "setForMatrix", False),
5766 ]
5767 helpers.convert_mapping_to_xml(
5768 descriptionsetter, data, mappings, fail_required=False
5769 )
5770
5771
5772 def doxygen(registry, xml_parent, data):
5773 """yaml: doxygen
5774 This plugin parses the Doxygen descriptor (Doxyfile) and provides a link to
5775 the generated Doxygen documentation.
5776
5777 Requires the Jenkins :jenkins-plugins:`Doxygen Plugin <doxygen>`.
5778
5779 :arg str doxyfile: The doxyfile path (required)
5780 :arg str slave: The node or label to pull the doxygen HTML files from
5781 (default '')
5782 :arg bool keep-all: Retain doxygen generation for each successful build
5783 (default false)
5784 :arg str folder: Folder where you run doxygen (default '')
5785
5786 Minimal Example:
5787
5788 .. literalinclude:: /../../tests/publishers/fixtures/doxygen-minimal.yaml
5789 :language: yaml
5790
5791 Full Example:
5792
5793 .. literalinclude:: /../../tests/publishers/fixtures/doxygen-full.yaml
5794 :language: yaml
5795 """
5796
5797 logger = logging.getLogger(__name__)
5798 p = XML.SubElement(xml_parent, "hudson.plugins.doxygen.DoxygenArchiver")
5799 mappings = [
5800 ("doxyfile", "doxyfilePath", None),
5801 ("slave", "runOnChild", ""),
5802 ("folder", "folderWhereYouRunDoxygen", ""),
5803 ]
5804 helpers.convert_mapping_to_xml(p, data, mappings, fail_required=True)
5805 # backward compatibility
5806 if "keepall" in data:
5807 if "keep-all" in data:
5808 XML.SubElement(p, "keepAll").text = str(data.get("keep-all", False)).lower()
5809 logger.warning(
5810 "The value of 'keepall' will be ignored " "in preference to 'keep-all'."
5811 )
5812 else:
5813 XML.SubElement(p, "keepAll").text = str(data.get("keepall", False)).lower()
5814 logger.warning("'keepall' is deprecated please use 'keep-all'")
5815 else:
5816 XML.SubElement(p, "keepAll").text = str(data.get("keep-all", False)).lower()
5817
5818
5819 def docker_stop_container(registry, xml_parent, data):
5820 """yaml: docker-stop-container
5821 This plugin allows removing stopped docker containers.
5822 It requires the :jenkins-plugins:`Docker build step plugin
5823 <docker-build-step>`.
5824
5825 :arg bool remove-stopped-containers: Boolean value to remove
5826 stopped docker containers (default False)
5827
5828 Minimal Example:
5829 .. literalinclude:: /../../tests/
5830 publishers/fixtures/docker-stop-container-minimal.yaml
5831
5832 Full Example:
5833 .. literalinclude:: /../../tests/
5834 publishers/fixtures/docker-stop-container-full.yaml
5835 """
5836 docker_stop_container = XML.SubElement(
5837 xml_parent,
5838 "com.nirima.jenkins.plugins.docker" ".publisher.DockerPublisherControl",
5839 )
5840 docker_stop_container.set("plugin", "docker-plugin")
5841 mapping = [("remove-stopped-containers", "remove", False)]
5842 helpers.convert_mapping_to_xml(
5843 docker_stop_container, data, mapping, fail_required=False
5844 )
5845
5846
5847 def sitemonitor(registry, xml_parent, data):
5848 """yaml: sitemonitor
5849 This plugin checks the availability of an url.
5850
5851 It requires the :jenkins-plugins:`sitemonitor plugin <sitemonitor>`.
5852
5853 :arg list sites: List of URLs to check
5854
5855 Minimal Example:
5856
5857 .. literalinclude::
5858 /../../tests/publishers/fixtures/sitemonitor-minimal.yaml
5859 :language: yaml
5860
5861 Full Example:
5862
5863 .. literalinclude:: /../../tests/publishers/fixtures/sitemonitor-full.yaml
5864 :language: yaml
5865 """
5866 mon = XML.SubElement(xml_parent, "hudson.plugins.sitemonitor.SiteMonitorRecorder")
5867 if data.get("sites"):
5868 sites = XML.SubElement(mon, "mSites")
5869 for siteurl in data.get("sites"):
5870 site = XML.SubElement(sites, "hudson.plugins.sitemonitor.model.Site")
5871 XML.SubElement(site, "mUrl").text = siteurl["url"]
5872
5873
5874 def testng(registry, xml_parent, data):
5875 """yaml: testng
5876 This plugin publishes TestNG test reports.
5877
5878 Requires the Jenkins :jenkins-plugins:`TestNG Results Plugin
5879 <testng-plugin>`.
5880
5881 :arg str pattern: filename pattern to locate the TestNG XML report files
5882 (required)
5883 :arg bool escape-test-description: escapes the description string
5884 associated with the test method while displaying test method details
5885 (default true)
5886 :arg bool escape-exception-msg: escapes the test method's exception
5887 messages. (default true)
5888 :arg bool fail-on-failed-test-config: Allows for a distinction between
5889 failing tests and failing configuration methods (>=1.10) (default
5890 false)
5891 :arg bool show-failed-builds: include results from failed builds in the
5892 trend graph (>=1.6) (default false)
5893 :arg int unstable-skips: Build is marked UNSTABLE if the number/percentage
5894 of skipped tests exceeds the specified threshold (>=1.11) (default 100)
5895 :arg int unstable-fails: Build is marked UNSTABLE if the number/percentage
5896 of failed tests exceeds the specified threshold (>=1.11) (default 0)
5897 :arg int failed-skips: Build is marked FAILURE if the number/percentage of
5898 skipped tests exceeds the specified threshold (>=1.11) (default 100)
5899 :arg int failed-fails: Build is marked FAILURE if the number/percentage of
5900 failed tests exceeds the specified threshold (>=1.11) (default 100)
5901 :arg str threshold-mode: Interpret threshold as number of tests or
5902 percentage of tests (>=1.11) (default percentage)
5903
5904 Full Example:
5905
5906 .. literalinclude:: /../../tests/publishers/fixtures/testng-full.yaml
5907 :language: yaml
5908
5909 Minimal Example:
5910
5911 .. literalinclude:: /../../tests/publishers/fixtures/testng-minimal.yaml
5912 :language: yaml
5913 """
5914
5915 reporter = XML.SubElement(xml_parent, "hudson.plugins.testng.Publisher")
5916 reporter.set("plugin", "testng-plugin")
5917 threshold_modes = {"number": 1, "percentage": 2}
5918
5919 mappings = [
5920 ("pattern", "reportFilenamePattern", None),
5921 ("escape-test-description", "escapeTestDescp", True),
5922 ("escape-exception-msg", "escapeExceptionMsg", True),
5923 ("fail-on-failed-test-config", "failureOnFailedTestConfig", False),
5924 ("show-failed-builds", "showFailedBuilds", False),
5925 ("unstable-skips", "unstableSkips", 100),
5926 ("unstable-fails", "unstableFails", 0),
5927 ("failed-skips", "failedSkips", 100),
5928 ("failed-fails", "failedFails", 100),
5929 ("threshold-mode", "thresholdMode", "percentage", threshold_modes),
5930 ]
5931 helpers.convert_mapping_to_xml(reporter, data, mappings, fail_required=True)
5932
5933
5934 def artifact_deployer(registry, xml_parent, data):
5935 """yaml: artifact-deployer
5936 This plugin makes it possible to copy artifacts to remote locations.
5937
5938 Requires the Jenkins :jenkins-plugins:`ArtifactDeployer Plugin
5939 <artifactdeployer>`.
5940
5941 :arg list entries:
5942 :entries:
5943 * **files** (`str`) - files to deploy
5944 * **basedir** (`str`) - the dir from files are deployed
5945 * **excludes** (`str`) - the mask to exclude files
5946 * **remote** (`str`) - a remote output directory
5947 * **flatten** (`bool`) - ignore the source directory structure
5948 (default false)
5949 * **delete-remote** (`bool`) - clean-up remote directory
5950 before deployment (default false)
5951 * **delete-remote-artifacts** (`bool`) - delete remote artifacts
5952 when the build is deleted (default false)
5953 * **fail-no-files** (`bool`) - fail build if there are no files
5954 (default false)
5955 * **groovy-script** (`str`) - execute a Groovy script
5956 before a build is deleted
5957
5958 :arg bool deploy-if-fail: Deploy if the build is failed (default false)
5959
5960 Example:
5961
5962 .. literalinclude:: /../../tests/publishers/fixtures/artifact-dep.yaml
5963 :language: yaml
5964 """
5965
5966 deployer = XML.SubElement(
5967 xml_parent,
5968 "org.jenkinsci.plugins.artifactdeployer." "ArtifactDeployerPublisher",
5969 )
5970 if data is None or "entries" not in data:
5971 raise Exception("entries field is missing")
5972 elif data.get("entries", None) is None:
5973 entries = XML.SubElement(deployer, "entries", {"class": "empty-list"})
5974 else:
5975 entries = XML.SubElement(deployer, "entries")
5976 for entry in data.get("entries"):
5977 deployer_entry = XML.SubElement(
5978 entries, "org.jenkinsci.plugins.artifactdeployer.ArtifactDeployerEntry"
5979 )
5980 XML.SubElement(deployer_entry, "includes").text = entry.get("files")
5981 XML.SubElement(deployer_entry, "basedir").text = entry.get("basedir")
5982 XML.SubElement(deployer_entry, "excludes").text = entry.get("excludes")
5983 XML.SubElement(deployer_entry, "remote").text = entry.get("remote")
5984 XML.SubElement(deployer_entry, "flatten").text = str(
5985 entry.get("flatten", False)
5986 ).lower()
5987 XML.SubElement(deployer_entry, "deleteRemote").text = str(
5988 entry.get("delete-remote", False)
5989 ).lower()
5990 XML.SubElement(deployer_entry, "deleteRemoteArtifacts").text = str(
5991 entry.get("delete-remote-artifacts", False)
5992 ).lower()
5993 XML.SubElement(deployer_entry, "failNoFilesDeploy").text = str(
5994 entry.get("fail-no-files", False)
5995 ).lower()
5996 XML.SubElement(deployer_entry, "groovyExpression").text = entry.get(
5997 "groovy-script"
5998 )
5999 deploy_if_fail = str(data.get("deploy-if-fail", False)).lower()
6000 XML.SubElement(deployer, "deployEvenBuildFail").text = deploy_if_fail
6001
6002
6003 def s3(registry, xml_parent, data):
6004 """yaml: s3
6005 Upload build artifacts to Amazon S3.
6006
6007 Requires the Jenkins :jenkins-plugins:`S3 plugin <s3>`.
6008
6009 :arg str s3-profile: Globally-defined S3 profile to use
6010 :arg bool dont-wait-for-concurrent-builds: Don't wait
6011 for completion of concurrent builds before publishing to S3
6012 (default false)
6013 :arg list entries:
6014 :entries:
6015 * **destination-bucket** (`str`) - Destination S3 bucket
6016 * **source-files** (`str`) - Source files (Ant glob syntax)
6017 * **storage-class** (`str`) - S3 storage class; one of "STANDARD"
6018 or "REDUCED_REDUNDANCY"
6019 * **bucket-region** (`str`) - S3 bucket region (capitalized with
6020 underscores)
6021 * **upload-on-failure** (`bool`) - Upload files even if the build
6022 failed (default false)
6023 * **upload-from-slave** (`bool`) - Perform the upload directly from
6024 the Jenkins slave rather than the master node. (default false)
6025 * **managed-artifacts** (`bool`) - Let Jenkins fully manage the
6026 published artifacts, similar to when artifacts are published to
6027 the Jenkins master. (default false)
6028 * **s3-encryption** (`bool`) - Use S3 AES-256 server side encryption
6029 support. (default false)
6030 * **flatten** (`bool`) - Ignore the directory structure of the
6031 artifacts in the source project and copy all matching artifacts
6032 directly into the specified bucket. (default false)
6033 :arg list metadata-tags:
6034 :metadata-tags:
6035 * **key** Metadata key for files from this build. It will be
6036 prefixed by "x-amz-meta-" when uploaded to S3. Can contain macros
6037 (e.g. environment variables).
6038 * **value** Metadata value associated with the key. Can contain macros.
6039
6040 Example:
6041
6042 .. literalinclude:: /../../tests/publishers/fixtures/s3001.yaml
6043 :language: yaml
6044 """
6045 deployer = XML.SubElement(xml_parent, "hudson.plugins.s3.S3BucketPublisher")
6046 if data is None or not data.get("entries"):
6047 raise JenkinsJobsException("No filesets defined.")
6048
6049 XML.SubElement(deployer, "dontWaitForConcurrentBuildCompletion").text = str(
6050 data.get("dont-wait-for-concurrent-builds", False)
6051 ).lower()
6052
6053 XML.SubElement(deployer, "profileName").text = data.get("s3-profile")
6054
6055 entries = XML.SubElement(deployer, "entries")
6056
6057 for entry in data.get("entries"):
6058 fileset = XML.SubElement(entries, "hudson.plugins.s3.Entry")
6059
6060 # xml keys -> yaml keys
6061 settings = [
6062 ("bucket", "destination-bucket", ""),
6063 ("sourceFile", "source-files", ""),
6064 ("storageClass", "storage-class", ""),
6065 ("selectedRegion", "bucket-region", ""),
6066 ("noUploadOnFailure", "upload-on-failure", False),
6067 ("uploadFromSlave", "upload-from-slave", False),
6068 ("managedArtifacts", "managed-artifacts", False),
6069 ("useServerSideEncryption", "s3-encryption", False),
6070 ("flatten", "flatten", False),
6071 ]
6072
6073 for xml_key, yaml_key, default in settings:
6074 xml_config = XML.SubElement(fileset, xml_key)
6075 config_value = entry.get(yaml_key, default)
6076 if xml_key == "noUploadOnFailure":
6077 xml_config.text = str(not config_value).lower()
6078 elif isinstance(default, bool):
6079 xml_config.text = str(config_value).lower()
6080 else:
6081 xml_config.text = str(config_value)
6082
6083 metadata = XML.SubElement(deployer, "userMetadata")
6084 for tag in data.get("metadata-tags", []):
6085 pair = XML.SubElement(metadata, "hudson.plugins.s3.MetadataPair")
6086 XML.SubElement(pair, "key").text = tag.get("key")
6087 XML.SubElement(pair, "value").text = tag.get("value")
6088
6089
6090 def ruby_metrics(registry, xml_parent, data):
6091 """yaml: ruby-metrics
6092 Rcov plugin parses rcov html report files and
6093 shows it in Jenkins with a trend graph.
6094
6095 Requires the Jenkins :jenkins-plugins:`Ruby metrics plugin
6096 <rubyMetrics>`.
6097
6098 :arg str report-dir: Relative path to the coverage report directory
6099 :arg dict targets:
6100
6101 :targets: (total-coverage, code-coverage)
6102
6103 * **healthy** (`int`): Healthy threshold
6104 * **unhealthy** (`int`): Unhealthy threshold
6105 * **unstable** (`int`): Unstable threshold
6106
6107 Example:
6108
6109 .. literalinclude:: /../../tests/publishers/fixtures/ruby-metrics.yaml
6110 :language: yaml
6111 """
6112
6113 metrics = XML.SubElement(
6114 xml_parent, "hudson.plugins.rubyMetrics.rcov.RcovPublisher"
6115 )
6116 report_dir = data.get("report-dir", "")
6117 XML.SubElement(metrics, "reportDir").text = report_dir
6118 targets = XML.SubElement(metrics, "targets")
6119 if "target" in data:
6120 for t in data["target"]:
6121 if not ("code-coverage" in t or "total-coverage" in t):
6122 raise JenkinsJobsException("Unrecognized target name")
6123 el = XML.SubElement(
6124 targets, "hudson.plugins.rubyMetrics.rcov.model.MetricTarget"
6125 )
6126 if "total-coverage" in t:
6127 XML.SubElement(el, "metric").text = "TOTAL_COVERAGE"
6128 else:
6129 XML.SubElement(el, "metric").text = "CODE_COVERAGE"
6130 for threshold_name, threshold_value in next(iter(t.values())).items():
6131 elname = threshold_name.lower()
6132 XML.SubElement(el, elname).text = str(threshold_value)
6133 else:
6134 raise JenkinsJobsException("Coverage metric targets must be set")
6135
6136
6137 def fitnesse(registry, xml_parent, data):
6138 """yaml: fitnesse
6139 Publish Fitnesse test results
6140
6141 Requires the Jenkins :jenkins-plugins:`Fitnesse plugin <fitnesse>`.
6142
6143 :arg str results: path specifier for results files
6144
6145 Example:
6146
6147 .. literalinclude:: /../../tests/publishers/fixtures/fitnesse001.yaml
6148 :language: yaml
6149 """
6150 fitnesse = XML.SubElement(
6151 xml_parent, "hudson.plugins.fitnesse.FitnesseResultsRecorder"
6152 )
6153 results = data.get("results", "")
6154 XML.SubElement(fitnesse, "fitnessePathToXmlResultsIn").text = results
6155
6156
6157 def valgrind(registry, xml_parent, data):
6158 """yaml: valgrind
6159 This plugin publishes Valgrind Memcheck XML results.
6160
6161 Requires the Jenkins :jenkins-plugins:`Valgrind Plugin <valgrind>`.
6162
6163 :arg str pattern: Filename pattern to locate the Valgrind XML report files
6164 (required)
6165 :arg dict thresholds: Mark build as failed or unstable if the number of
6166 errors exceeds a threshold. All threshold values are optional.
6167
6168 :thresholds:
6169 * **unstable** (`dict`)
6170 :unstable: * **invalid-read-write** (`int`)
6171 * **definitely-lost** (`int`)
6172 * **total** (`int`)
6173 * **failed** (`dict`)
6174 :failed: * **invalid-read-write** (`int`)
6175 * **definitely-lost** (`int`)
6176 * **total** (`int`)
6177 :arg bool fail-no-reports: Fail build if no reports are found
6178 (default false)
6179 :arg bool fail-invalid-reports: Fail build if reports are malformed
6180 (default false)
6181 :arg bool publish-if-aborted: Publish results for aborted builds
6182 (default false)
6183 :arg bool publish-if-failed: Publish results for failed builds
6184 (default false)
6185
6186 Example:
6187
6188 .. literalinclude:: /../../tests/publishers/fixtures/valgrind001.yaml
6189 :language: yaml
6190 """
6191 p = XML.SubElement(xml_parent, "org.jenkinsci.plugins.valgrind.ValgrindPublisher")
6192 p = XML.SubElement(p, "valgrindPublisherConfig")
6193
6194 if "pattern" not in data:
6195 raise JenkinsJobsException("A filename pattern must be specified.")
6196
6197 XML.SubElement(p, "pattern").text = data["pattern"]
6198
6199 dthresholds = data.get("thresholds", {})
6200
6201 for threshold in ["unstable", "failed"]:
6202 dthreshold = dthresholds.get(threshold, {})
6203 threshold = threshold.replace("failed", "fail")
6204
6205 ThresholdInvalidReadWrite = "%sThresholdInvalidReadWrite" % threshold
6206 ThresholdDefinitelyLost = "%sThresholdDefinitelyLost" % threshold
6207 ThresholdTotal = "%sThresholdTotal" % threshold
6208
6209 threshold_mapping = [
6210 ("invalid-read-write", ThresholdInvalidReadWrite, ""),
6211 ("definitely-lost", ThresholdDefinitelyLost, ""),
6212 ("total", ThresholdTotal, ""),
6213 ]
6214 helpers.convert_mapping_to_xml(
6215 p, dthreshold, threshold_mapping, fail_required=True
6216 )
6217
6218 mapping = [
6219 ("fail-no-reports", "failBuildOnMissingReports", False),
6220 ("fail-invalid-reports", "failBuildOnInvalidReports", False),
6221 ("publish-if-aborted", "publishResultsForAbortedBuilds", False),
6222 ("publish-if-failed", "publishResultsForFailedBuilds", False),
6223 ]
6224 helpers.convert_mapping_to_xml(p, data, mapping, fail_required=True)
6225
6226
6227 def pmd(registry, xml_parent, data):
6228 """yaml: pmd
6229 Publish trend reports with PMD.
6230
6231 Requires the Jenkins PMD Plugin (:jenkins-github:`pmd-plugin`).
6232
6233 The PMD component accepts a dictionary with the following values:
6234
6235 :arg str pattern: Report filename pattern (optional)
6236 :arg bool can-run-on-failed: Also runs for failed builds, instead of just
6237 stable or unstable builds (default false)
6238 :arg bool should-detect-modules: Determines if Ant or Maven modules should
6239 be detected for all files that contain warnings (default false)
6240 :arg int healthy: Sunny threshold (optional)
6241 :arg int unhealthy: Stormy threshold (optional)
6242 :arg str health-threshold: Threshold priority for health status
6243 ('low', 'normal' or 'high', defaulted to 'low')
6244 :arg dict thresholds: Mark build as failed or unstable if the number of
6245 errors exceeds a threshold. (optional)
6246
6247 :thresholds:
6248 * **unstable** (`dict`)
6249 :unstable: * **total-all** (`int`)
6250 * **total-high** (`int`)
6251 * **total-normal** (`int`)
6252 * **total-low** (`int`)
6253 * **new-all** (`int`)
6254 * **new-high** (`int`)
6255 * **new-normal** (`int`)
6256 * **new-low** (`int`)
6257
6258 * **failed** (`dict`)
6259 :failed: * **total-all** (`int`)
6260 * **total-high** (`int`)
6261 * **total-normal** (`int`)
6262 * **total-low** (`int`)
6263 * **new-all** (`int`)
6264 * **new-high** (`int`)
6265 * **new-normal** (`int`)
6266 * **new-low** (`int`)
6267 :arg str default-encoding: Encoding for parsing or showing files (optional)
6268 :arg bool do-not-resolve-relative-paths: (default false)
6269 :arg bool dont-compute-new: If set to false, computes new warnings based on
6270 the reference build (default true)
6271 :arg bool use-previous-build-as-reference: determines whether to always
6272 use the previous build as the reference build (default false)
6273 :arg bool use-stable-build-as-reference: The number of new warnings will be
6274 calculated based on the last stable build, allowing reverts of unstable
6275 builds where the number of warnings was decreased. (default false)
6276 :arg bool use-delta-values: If set then the number of new warnings is
6277 calculated by subtracting the total number of warnings of the current
6278 build from the reference build.
6279 (default false)
6280
6281 Example:
6282
6283 .. literalinclude:: /../../tests/publishers/fixtures/pmd001.yaml
6284 :language: yaml
6285
6286 Full example:
6287
6288 .. literalinclude:: /../../tests/publishers/fixtures/pmd002.yaml
6289 :language: yaml
6290 """
6291
6292 xml_element = XML.SubElement(xml_parent, "hudson.plugins.pmd.PmdPublisher")
6293
6294 helpers.build_trends_publisher("[PMD] ", xml_element, data)
6295
6296
6297 def scan_build(registry, xml_parent, data):
6298 """yaml: scan-build
6299 Publishes results from the Clang scan-build static analyzer.
6300
6301 The scan-build report has to be generated in the directory
6302 ``${WORKSPACE}/clangScanBuildReports`` for the publisher to find it.
6303
6304 Requires the Jenkins :jenkins-plugins:`Clang Scan-Build Plugin
6305 <clang-scanbuild>`.
6306
6307 :arg bool mark-unstable: Mark build as unstable if the number of bugs
6308 exceeds a threshold (default false)
6309 :arg int threshold: Threshold for marking builds as unstable (default 0)
6310 :arg str exclude-paths: Comma separated paths to exclude from reports
6311 (>=1.5) (default '')
6312 :arg str report-folder: Folder where generated reports are located
6313 (>=1.7) (default 'clangScanBuildReports')
6314
6315 Full Example:
6316
6317 .. literalinclude:: /../../tests/publishers/fixtures/scan-build-full.yaml
6318 :language: yaml
6319
6320 Minimal Example:
6321
6322 .. literalinclude::
6323 /../../tests/publishers/fixtures/scan-build-minimal.yaml
6324 :language: yaml
6325 """
6326 p = XML.SubElement(
6327 xml_parent, "jenkins.plugins.clangscanbuild.publisher.ClangScanBuildPublisher"
6328 )
6329 p.set("plugin", "clang-scanbuild")
6330
6331 mappings = [
6332 ("mark-unstable", "markBuildUnstableWhenThresholdIsExceeded", False),
6333 ("threshold", "bugThreshold", 0),
6334 ("exclude-paths", "clangexcludedpaths", ""),
6335 ("report-folder", "reportFolderName", "clangScanBuildReports"),
6336 ]
6337 helpers.convert_mapping_to_xml(p, data, mappings, fail_required=True)
6338
6339
6340 def dry(registry, xml_parent, data):
6341 """yaml: dry
6342 Publish trend reports with DRY.
6343
6344 Requires the Jenkins DRY Plugin (:jenkins-github:`dry-plugin`).
6345
6346 The DRY component accepts a dictionary with the following values:
6347
6348 :arg str pattern: Report filename pattern (default '')
6349 :arg bool can-run-on-failed: Also runs for failed builds, instead of just
6350 stable or unstable builds (default false)
6351 :arg bool should-detect-modules: Determines if Ant or Maven modules should
6352 be detected for all files that contain warnings (default false)
6353 :arg int healthy: Sunny threshold (default '')
6354 :arg int unhealthy: Stormy threshold (default '')
6355 :arg str health-threshold: Threshold priority for health status
6356 ('low', 'normal' or 'high', defaulted to 'low')
6357 :arg int high-threshold: Minimum number of duplicated lines for high
6358 priority warnings. (default 50)
6359 :arg int normal-threshold: Minimum number of duplicated lines for normal
6360 priority warnings. (default 25)
6361 :arg dict thresholds: Mark build as failed or unstable if the number of
6362 errors exceeds a threshold. (default '')
6363
6364 :thresholds:
6365 * **unstable** (`dict`)
6366 :unstable: * **total-all** (`int`)
6367 * **total-high** (`int`)
6368 * **total-normal** (`int`)
6369 * **total-low** (`int`)
6370 * **new-all** (`int`)
6371 * **new-high** (`int`)
6372 * **new-normal** (`int`)
6373 * **new-low** (`int`)
6374
6375 * **failed** (`dict`)
6376 :failed: * **total-all** (`int`)
6377 * **total-high** (`int`)
6378 * **total-normal** (`int`)
6379 * **total-low** (`int`)
6380 * **new-all** (`int`)
6381 * **new-high** (`int`)
6382 * **new-normal** (`int`)
6383 * **new-low** (`int`)
6384 :arg str default-encoding: Encoding for parsing or showing files (optional)
6385 :arg bool do-not-resolve-relative-paths: (default false)
6386 :arg bool dont-compute-new: If set to false, computes new warnings based on
6387 the reference build (default true)
6388 :arg bool use-previous-build-as-reference: determines whether to always
6389 use the previous build as the reference build (default false)
6390 :arg bool use-stable-build-as-reference: The number of new warnings will be
6391 calculated based on the last stable build, allowing reverts of unstable
6392 builds where the number of warnings was decreased. (default false)
6393 :arg bool use-delta-values: If set then the number of new warnings is
6394 calculated by subtracting the total number of warnings of the current
6395 build from the reference build. (default false)
6396
6397 Example:
6398
6399 .. literalinclude:: /../../tests/publishers/fixtures/dry001.yaml
6400 :language: yaml
6401
6402 Full example:
6403
6404 .. literalinclude:: /../../tests/publishers/fixtures/dry004.yaml
6405 :language: yaml
6406 """
6407
6408 xml_element = XML.SubElement(xml_parent, "hudson.plugins.dry.DryPublisher")
6409
6410 helpers.build_trends_publisher("[DRY] ", xml_element, data)
6411
6412 # Add specific settings for this trends publisher
6413 settings = [
6414 ("high-threshold", "highThreshold", 50),
6415 ("normal-threshold", "normalThreshold", 25),
6416 ]
6417 helpers.convert_mapping_to_xml(xml_element, data, settings, fail_required=True)
6418
6419
6420 def shining_panda(registry, xml_parent, data):
6421 """yaml: shining-panda
6422 Publish coverage.py results. Requires the Jenkins
6423 :jenkins-plugins:`ShiningPanda Plugin <shiningpanda>`.
6424
6425 :arg str html-reports-directory: path to coverage.py html results
6426 (optional)
6427
6428 Example:
6429
6430 .. literalinclude:: /../../tests/publishers/fixtures/shiningpanda001.yaml
6431 :language: yaml
6432 """
6433 shining_panda_plugin = XML.SubElement(
6434 xml_parent, "jenkins.plugins.shiningpanda.publishers.CoveragePublisher"
6435 )
6436
6437 mapping = [("html-reports-directory", "htmlDir", None)]
6438 helpers.convert_mapping_to_xml(
6439 shining_panda_plugin, data, mapping, fail_required=False
6440 )
6441
6442
6443 def downstream_ext(registry, xml_parent, data):
6444 """yaml: downstream-ext
6445 Trigger multiple downstream jobs when a job is completed and
6446 condition is met.
6447
6448 Requires the Jenkins :jenkins-plugins:`Downstream-Ext Plugin
6449 <downstream-ext>`.
6450
6451 :arg list projects: Projects to build (required)
6452 :arg str condition: comparison condition used for the criteria.
6453 One of 'equal-or-over', 'equal-or-under', 'equal'
6454 (default 'equal-or-over')
6455 :arg str criteria: Trigger downstream job if build results meets
6456 condition. One of 'success', 'unstable', 'failure' or
6457 'aborted' (default 'success')
6458 :arg bool only-on-scm-change: Trigger only if downstream project
6459 has SCM changes (default false)
6460 :arg bool only-on-local-scm-change: Trigger only if current project
6461 has SCM changes (default false)
6462
6463 Example:
6464
6465 .. literalinclude::
6466 /../../tests/publishers/fixtures/downstream-ext002.yaml
6467 :language: yaml
6468 """
6469
6470 conditions = {
6471 "equal-or-over": "AND_HIGHER",
6472 "equal-or-under": "AND_LOWER",
6473 "equal": "EXACT",
6474 }
6475
6476 p = XML.SubElement(xml_parent, "hudson.plugins.downstream__ext.DownstreamTrigger")
6477
6478 if "projects" not in data:
6479 raise JenkinsJobsException("Missing list of downstream projects.")
6480
6481 XML.SubElement(p, "childProjects").text = ",".join(data["projects"])
6482
6483 th = XML.SubElement(p, "threshold")
6484
6485 criteria = data.get("criteria", "success").upper()
6486
6487 wr_threshold = hudson_model.THRESHOLDS[criteria]
6488 if criteria not in hudson_model.THRESHOLDS:
6489 raise JenkinsJobsException(
6490 "criteria must be one of %s" % ", ".join(hudson_model.THRESHOLDS.keys())
6491 )
6492 mapping = [
6493 ("name", "name", None),
6494 ("ordinal", "ordinal", None),
6495 ("color", "color", None),
6496 ("complete", "completeBuild", None),
6497 ]
6498 helpers.convert_mapping_to_xml(th, wr_threshold, mapping, fail_required=True)
6499
6500 condition_mapping = [
6501 ("condition", "thresholdStrategy", "equal-or-over", conditions),
6502 ("only-on-scm-change", "onlyIfSCMChanges", False),
6503 ("only-on-local-scm-change", "onlyIfLocalSCMChanges", False),
6504 ]
6505 helpers.convert_mapping_to_xml(p, data, condition_mapping, fail_required=True)
6506
6507
6508 def rundeck(registry, xml_parent, data):
6509 """yaml: rundeck
6510 Trigger a rundeck job when the build is complete.
6511
6512 Requires the Jenkins :jenkins-plugins:`RunDeck Plugin <rundeck>`.
6513
6514 :arg str job-id: The RunDeck job identifier. (required)
6515 This could be:
6516 * ID example : "42"
6517 * UUID example : "2027ce89-7924-4ecf-a963-30090ada834f"
6518 * reference, in the format : "project:group/job"
6519 :arg str options: List of options for the Rundeck job, in Java-Properties
6520 format: key=value (default "")
6521 :arg str node-filters: List of filters to optionally filter the nodes
6522 included by the job. (default "")
6523 :arg str tag: Used for on-demand job scheduling on rundeck: if a tag is
6524 specified, the job will only execute if the given tag is present in the
6525 SCM changelog. (default "")
6526 :arg bool wait-for-rundeck: If true Jenkins will wait for the job to
6527 complete, if false the job will be started and Jenkins will move on.
6528 (default false)
6529 :arg bool fail-the-build: If true a RunDeck job failure will cause the
6530 Jenkins build to fail. (default false)
6531
6532 Example:
6533
6534 .. literalinclude:: /../../tests/publishers/fixtures/rundeck001.yaml
6535 :language: yaml
6536
6537 Full example:
6538
6539 .. literalinclude:: /../../tests/publishers/fixtures/rundeck002.yaml
6540 :language: yaml
6541 """
6542
6543 p = XML.SubElement(xml_parent, "org.jenkinsci.plugins.rundeck.RundeckNotifier")
6544
6545 mappings = [
6546 ("job-id", "jobId", None),
6547 ("options", "options", ""),
6548 ("node-filters", "nodeFilters", ""),
6549 ("tag", "tag", ""),
6550 ("wait-for-rundeck", "shouldWaitForRundeckJob", False),
6551 ("fail-the-build", "shouldFailTheBuild", False),
6552 ]
6553 helpers.convert_mapping_to_xml(p, data, mappings, fail_required=True)
6554
6555
6556 def create_publishers(registry, action):
6557 dummy_parent = XML.Element("dummy")
6558 registry.dispatch("publisher", dummy_parent, action)
6559 return list(dummy_parent)
6560
6561
6562 def conditional_publisher(registry, xml_parent, data):
6563 """yaml: conditional-publisher
6564 Conditionally execute some post-build steps. Requires the Jenkins
6565 :jenkins-plugins:`Flexible Publish Plugin <flexible-publish>`.
6566
6567 A Flexible Publish list of Conditional Actions is created in Jenkins.
6568
6569 :arg str condition-kind: Condition kind that must be verified before the
6570 action is executed. Valid values and their additional attributes are
6571 described in the conditions_ table.
6572 :arg bool condition-aggregation: If true Matrix Aggregation will be
6573 enabled. (default false)
6574 :arg str condition-aggregation-kind: Condition Aggregation kind that
6575 must be verified before the
6576 action is executed. Valid values and their additional attributes are
6577 described in the conditions_ table.
6578 :arg str on-evaluation-failure: What should be the outcome of the build
6579 if the evaluation of the condition fails. Possible values are `fail`,
6580 `mark-unstable`, `run-and-mark-unstable`, `run` and `dont-run`.
6581 Default is `fail`.
6582 :arg list action: Action to run if the condition is verified. Item
6583 can be any publisher known by Jenkins Job Builder and supported
6584 by the Flexible Publish Plugin.
6585
6586 .. _conditions:
6587
6588 ================== ====================================================
6589 Condition kind Description
6590 ================== ====================================================
6591 always Condition is always verified
6592 never Condition is never verified
6593 boolean-expression Run the action if the expression expands to a
6594 representation of true
6595
6596 :condition-expression: Expression to expand
6597 current-status Run the action if the current build status is
6598 within the configured range
6599
6600 :condition-worst: Accepted values are SUCCESS,
6601 UNSTABLE, FAILURE, NOT_BUILD, ABORTED
6602 :condition-best: Accepted values are SUCCESS,
6603 UNSTABLE, FAILURE, NOT_BUILD, ABORTED
6604
6605 shell Run the action if the shell command succeeds
6606
6607 :condition-command: Shell command to execute
6608 windows-shell Similar to shell, except that commands will be
6609 executed by cmd, under Windows
6610
6611 :condition-command: Command to execute
6612 regexp Run the action if a regular expression matches
6613
6614 :condition-expression: Regular Expression
6615 :condition-searchtext: Text to match against
6616 the regular expression
6617 file-exists Run the action if a file exists
6618
6619 :condition-filename: Check existence of this file
6620 :condition-basedir: If condition-filename is
6621 relative, it will be considered relative to
6622 either `workspace`, `artifact-directory`,
6623 or `jenkins-home`. Default is `workspace`.
6624 ================== ====================================================
6625
6626 Single Conditional Action Example:
6627
6628 .. literalinclude:: \
6629 /../../tests/publishers/fixtures/conditional-publisher001.yaml
6630 :language: yaml
6631
6632 Multiple Conditional Actions Example
6633 (includes example of multiple actions per condition which requires
6634 v0.13 or higher of the Flexible Publish plugin):
6635
6636 .. literalinclude:: \
6637 /../../tests/publishers/fixtures/conditional-publisher003.yaml
6638 :language: yaml
6639
6640 :download:`Multiple Conditional Actions Example for pre-v0.13 versions
6641 <../../tests/publishers/fixtures/conditional-publisher002.yaml>`
6642
6643 """
6644
6645 def publish_condition_tag(cdata, prefix, condition_tag):
6646 kind = cdata["%s-kind" % prefix]
6647 ctag = XML.SubElement(cond_publisher, condition_tag)
6648 class_pkg = "org.jenkins_ci.plugins.run_condition"
6649
6650 if kind == "always":
6651 ctag.set("class", class_pkg + ".core.AlwaysRun")
6652 elif kind == "never":
6653 ctag.set("class", class_pkg + ".core.NeverRun")
6654 elif kind == "boolean-expression":
6655 ctag.set("class", class_pkg + ".core.BooleanCondition")
6656 XML.SubElement(ctag, "token").text = cdata["%s-expression" % prefix]
6657 elif kind == "current-status":
6658 ctag.set("class", class_pkg + ".core.StatusCondition")
6659 wr = XML.SubElement(ctag, "worstResult")
6660 wr_name = cdata["%s-worst" % prefix]
6661 if wr_name not in hudson_model.THRESHOLDS:
6662 raise JenkinsJobsException(
6663 "threshold must be one of %s"
6664 % ", ".join(hudson_model.THRESHOLDS.keys())
6665 )
6666 wr_threshold = hudson_model.THRESHOLDS[wr_name]
6667 XML.SubElement(wr, "name").text = wr_threshold["name"]
6668 XML.SubElement(wr, "ordinal").text = wr_threshold["ordinal"]
6669 XML.SubElement(wr, "color").text = wr_threshold["color"]
6670 XML.SubElement(wr, "completeBuild").text = str(
6671 wr_threshold["complete"]
6672 ).lower()
6673
6674 br = XML.SubElement(ctag, "bestResult")
6675 br_name = cdata["%s-best" % prefix]
6676 if br_name not in hudson_model.THRESHOLDS:
6677 raise JenkinsJobsException(
6678 "threshold must be one of %s"
6679 % ", ".join(hudson_model.THRESHOLDS.keys())
6680 )
6681 br_threshold = hudson_model.THRESHOLDS[br_name]
6682 XML.SubElement(br, "name").text = br_threshold["name"]
6683 XML.SubElement(br, "ordinal").text = br_threshold["ordinal"]
6684 XML.SubElement(br, "color").text = br_threshold["color"]
6685 XML.SubElement(br, "completeBuild").text = str(
6686 wr_threshold["complete"]
6687 ).lower()
6688 elif kind == "shell":
6689 ctag.set("class", class_pkg + ".contributed.ShellCondition")
6690 XML.SubElement(ctag, "command").text = cdata["%s-command" % prefix]
6691 elif kind == "windows-shell":
6692 ctag.set("class", class_pkg + ".contributed.BatchFileCondition")
6693 XML.SubElement(ctag, "command").text = cdata["%s-command" % prefix]
6694 elif kind == "regexp":
6695 ctag.set("class", class_pkg + ".core.ExpressionCondition")
6696 XML.SubElement(ctag, "expression").text = cdata["%s-expression" % prefix]
6697 XML.SubElement(ctag, "label").text = cdata["%s-searchtext" % prefix]
6698 elif kind == "file-exists":
6699 ctag.set("class", class_pkg + ".core.FileExistsCondition")
6700 XML.SubElement(ctag, "file").text = cdata["%s-filename" % prefix]
6701 basedir = cdata.get("%s-basedir", "workspace")
6702 basedir_tag = XML.SubElement(ctag, "baseDir")
6703 if "workspace" == basedir:
6704 basedir_tag.set("class", class_pkg + ".common.BaseDirectory$Workspace")
6705 elif "artifact-directory" == basedir:
6706 basedir_tag.set(
6707 "class", class_pkg + ".common." "BaseDirectory$ArtifactsDir"
6708 )
6709 elif "jenkins-home" == basedir:
6710 basedir_tag.set(
6711 "class", class_pkg + ".common." "BaseDirectory$JenkinsHome"
6712 )
6713 else:
6714 raise JenkinsJobsException(
6715 "%s is not a valid %s-kind " "value." % (kind, prefix)
6716 )
6717
6718 def publish_condition(cdata):
6719 return publish_condition_tag(cdata, "condition", condition_tag)
6720
6721 def publish_aggregation_condition(cdata):
6722 return publish_condition_tag(
6723 cdata, "condition-aggregation", aggregation_condition_tag
6724 )
6725
6726 def publish_action(parent, action):
6727 for edited_node in create_publishers(registry, action):
6728 if not use_publisher_list:
6729 edited_node.set("class", edited_node.tag)
6730 # sort attributes alphabetically
6731 attrib = edited_node.attrib
6732 if len(attrib) > 1:
6733 attribs = sorted(attrib.items())
6734 attrib.clear()
6735 attrib.update(attribs)
6736 edited_node.tag = "publisher"
6737 parent.append(edited_node)
6738
6739 flex_publisher_tag = (
6740 "org.jenkins__ci.plugins.flexible__publish." "FlexiblePublisher"
6741 )
6742 cond_publisher_tag = (
6743 "org.jenkins__ci.plugins.flexible__publish." "ConditionalPublisher"
6744 )
6745
6746 root_tag = XML.SubElement(xml_parent, flex_publisher_tag)
6747 publishers_tag = XML.SubElement(root_tag, "publishers")
6748 condition_tag = "condition"
6749 aggregation_condition_tag = "aggregationCondition"
6750
6751 evaluation_classes_pkg = "org.jenkins_ci.plugins.run_condition"
6752 evaluation_classes = {
6753 "fail": evaluation_classes_pkg + ".BuildStepRunner$Fail",
6754 "mark-unstable": evaluation_classes_pkg + ".BuildStepRunner$Unstable",
6755 "run-and-mark-unstable": evaluation_classes_pkg
6756 + ".BuildStepRunner$RunUnstable",
6757 "run": evaluation_classes_pkg + ".BuildStepRunner$Run",
6758 "dont-run": evaluation_classes_pkg + ".BuildStepRunner$DontRun",
6759 }
6760
6761 plugin_ver = registry.get_plugin_version("Flexible Publish Plugin")
6762
6763 # Support for MatrixAggregator was added in v0.11
6764 # See JENKINS-14494
6765 has_matrix_aggregator = plugin_ver >= "0.11"
6766
6767 for cond_action in data:
6768 cond_publisher = XML.SubElement(publishers_tag, cond_publisher_tag)
6769 publish_condition(cond_action)
6770 condition_aggregation = cond_action.get("condition-aggregation", False)
6771 if condition_aggregation and has_matrix_aggregator:
6772 publish_aggregation_condition(cond_action)
6773 elif condition_aggregation:
6774 raise JenkinsJobsException(
6775 "Matrix Aggregation is not supported " "in your plugin version."
6776 )
6777 evaluation_flag = cond_action.get("on-evaluation-failure", "fail")
6778 if evaluation_flag not in evaluation_classes.keys():
6779 raise JenkinsJobsException(
6780 "on-evaluation-failure value "
6781 "specified is not valid. Must be one "
6782 "of: %s" % evaluation_classes.keys()
6783 )
6784
6785 evaluation_class = evaluation_classes[evaluation_flag]
6786 XML.SubElement(cond_publisher, "runner").set("class", evaluation_class)
6787
6788 if "action" in cond_action:
6789 actions = cond_action["action"]
6790
6791 action_parent = cond_publisher
6792
6793 # XML tag changed from publisher to publisherList in v0.13
6794 # check the plugin version to determine further operations
6795 use_publisher_list = plugin_ver >= "0.13"
6796
6797 if use_publisher_list:
6798 action_parent = XML.SubElement(cond_publisher, "publisherList")
6799 else:
6800 # Check the length of actions list for versions prior to 0.13.
6801 # Flexible Publish will overwrite action if more than one is
6802 # specified. Limit the action list to one element.
6803 if len(actions) != 1:
6804 raise JenkinsJobsException(
6805 "Only one action may be " "specified for each condition."
6806 )
6807 for action in actions:
6808 publish_action(action_parent, action)
6809 else:
6810 raise JenkinsJobsException("action must be set for each condition")
6811
6812
6813 def scoverage(registry, xml_parent, data):
6814 """yaml: scoverage
6815 Publish scoverage results as a trend graph.
6816 Requires the Jenkins :jenkins-plugins:`Scoverage Plugin <scoverage>`.
6817
6818 :arg str report-directory: This is a directory that specifies the locations
6819 where the xml scoverage report is generated (required)
6820 :arg str report-file: This is a file name that is given to the xml
6821 scoverage report (required)
6822
6823 Example:
6824
6825 .. literalinclude:: /../../tests/publishers/fixtures/scoverage001.yaml
6826 :language: yaml
6827 """
6828 scoverage = XML.SubElement(
6829 xml_parent, "org.jenkinsci.plugins.scoverage.ScoveragePublisher"
6830 )
6831 scoverage.set("plugin", "scoverage")
6832
6833 mappings = [
6834 ("report-directory", "reportDir", None),
6835 ("report-file", "reportFile", None),
6836 ]
6837 helpers.convert_mapping_to_xml(scoverage, data, mappings, fail_required=True)
6838
6839
6840 def display_upstream_changes(registry, xml_parent, data):
6841 """yaml: display-upstream-changes
6842 Display SCM changes of upstream jobs. Requires the Jenkins
6843 :jenkins-plugins:`Display Upstream Changes Plugin
6844 <display-upstream-changes>`.
6845
6846 Example:
6847
6848 .. literalinclude:: \
6849 /../../tests/publishers/fixtures/display-upstream-changes.yaml
6850 """
6851 XML.SubElement(
6852 xml_parent,
6853 "jenkins.plugins.displayupstreamchanges." "DisplayUpstreamChangesRecorder",
6854 )
6855
6856
6857 def gatling(registry, xml_parent, data):
6858 """yaml: gatling
6859 Publish gatling results as a trend graph
6860 Requires the Jenkins :jenkins-plugins:`Gatling Plugin <gatling>`.
6861
6862 Example:
6863
6864 .. literalinclude:: /../../tests/publishers/fixtures/gatling001.yaml
6865 :language: yaml
6866 """
6867 gatling = XML.SubElement(xml_parent, "io.gatling.jenkins.GatlingPublisher")
6868 mapping = [("", "enabled", "true")]
6869 helpers.convert_mapping_to_xml(gatling, data, mapping, fail_required=True)
6870
6871
6872 def logstash(registry, xml_parent, data):
6873 """yaml: logstash
6874 Send job's console log to Logstash for processing and analyis of
6875 your job data. Also stores test metrics from Junit.
6876 Requires the Jenkins :jenkins-plugins:`Logstash Plugin <logstash>`.
6877
6878 :arg int max-lines: The maximum number of log lines to send to Logstash.
6879 (default 1000)
6880 :arg bool fail-build: Mark build as failed if this step fails.
6881 (default false)
6882
6883 Minimal Example:
6884
6885 .. literalinclude:: /../../tests/publishers/fixtures/logstash-min.yaml
6886 :language: yaml
6887
6888 Full Example:
6889
6890 .. literalinclude:: /../../tests/publishers/fixtures/logstash-full.yaml
6891 :language: yaml
6892 """
6893
6894 logstash = XML.SubElement(xml_parent, "jenkins.plugins.logstash.LogstashNotifier")
6895 logstash.set("plugin", "logstash")
6896
6897 mapping = [("max-lines", "maxLines", 1000), ("fail-build", "failBuild", False)]
6898 helpers.convert_mapping_to_xml(logstash, data, mapping, fail_required=True)
6899
6900
6901 def image_gallery(registry, xml_parent, data):
6902 """yaml: image-gallery
6903 Produce an image gallery using Javascript library. Requires the Jenkins
6904 :jenkins-plugins:`Image Gallery Plugin <image-gallery>`.
6905
6906 :arg str gallery-type:
6907
6908 :gallery-type values:
6909 * **archived-images-gallery** (default)
6910 * **in-folder-comparative-gallery**
6911 * **multiple-folder-comparative-gallery**
6912 :arg str title: gallery title (optional)
6913 :arg int image-width: width of the image (optional)
6914 :arg bool unstable-if-no-artifacts: mark build as unstable
6915 if no archived artifacts were found (default false)
6916 :arg str includes: include pattern (valid for archived-images-gallery
6917 gallery)
6918 :arg str base-root-folder: base root dir (valid for comparative gallery)
6919 :arg int image-inner-width: width of the image displayed in the inner
6920 gallery popup (valid for comparative gallery, optional)
6921
6922 Example:
6923
6924 .. literalinclude:: /../../tests/publishers/fixtures/image-gallery001.yaml
6925
6926 """
6927
6928 def include_comparative_elements(gallery_parent_elem, gallery):
6929 XML.SubElement(gallery_parent_elem, "baseRootFolder").text = str(
6930 gallery.get("base-root-folder", "")
6931 )
6932 image_inner_width = gallery.get("image-inner-width", "")
6933 if image_inner_width:
6934 XML.SubElement(gallery_parent_elem, "imageInnerWidth").text = str(
6935 image_inner_width
6936 )
6937
6938 package_prefix = "org.jenkinsci.plugins.imagegallery."
6939 builder = XML.SubElement(xml_parent, package_prefix + "ImageGalleryRecorder")
6940 image_galleries = XML.SubElement(builder, "imageGalleries")
6941 galleries = {
6942 "archived-images-gallery": package_prefix + "imagegallery."
6943 "ArchivedImagesGallery",
6944 "in-folder-comparative-gallery": package_prefix + "comparative."
6945 "InFolderComparativeArchivedImagesGallery",
6946 "multiple-folder-comparative-gallery": package_prefix + "comparative."
6947 "MultipleFolderComparativeArchivedImagesGallery",
6948 }
6949 for gallery_def in data:
6950 gallery_type = gallery_def.get("gallery-type", "archived-images-gallery")
6951 if gallery_type not in galleries:
6952 raise InvalidAttributeError("gallery-type", gallery_type, galleries.keys())
6953 gallery_config = XML.SubElement(image_galleries, galleries[gallery_type])
6954 XML.SubElement(gallery_config, "title").text = str(gallery_def.get("title", ""))
6955 image_width = str(gallery_def.get("image-width", ""))
6956 if image_width:
6957 XML.SubElement(gallery_config, "imageWidth").text = str(image_width)
6958 XML.SubElement(
6959 gallery_config, "markBuildAsUnstableIfNoArchivesFound"
6960 ).text = str(gallery_def.get("unstable-if-no-artifacts", False))
6961 if gallery_type == "archived-images-gallery":
6962 XML.SubElement(gallery_config, "includes").text = str(
6963 gallery_def.get("includes", "")
6964 )
6965 if gallery_type == "in-folder-comparative-gallery":
6966 include_comparative_elements(gallery_config, gallery_def)
6967 if gallery_type == "multiple-folder-comparative-gallery":
6968 include_comparative_elements(gallery_config, gallery_def)
6969
6970
6971 def naginator(registry, xml_parent, data):
6972 """yaml: naginator
6973 Automatically reschedule a build after a build failure
6974 Requires the Jenkins :jenkins-plugins:`Naginator Plugin <naginator>`.
6975
6976 :arg bool rerun-unstable-builds: Rerun build for unstable builds as well
6977 as failures (default false)
6978 :arg bool rerun-matrix-part: Rerun build only for failed parts on the
6979 matrix (>=1.12) (default false)
6980 :arg int fixed-delay: Fixed delay in seconds before retrying build (cannot
6981 be used with progressive-delay-increment or progressive-delay-maximum.
6982 This is the default delay type. (default 0)
6983 :arg int progressive-delay-increment: Progressive delay in seconds before
6984 retrying build increment (cannot be used when fixed-delay is being
6985 used) (default 0)
6986 :arg int progressive-delay-maximum: Progressive delay in seconds before
6987 retrying maximum delay (cannot be used when fixed-delay is being used)
6988 (default 0)
6989 :arg int max-failed-builds: Maximum number of successive failed builds
6990 (default 0)
6991 :arg str regular-expression: Only rerun build if regular expression is
6992 found in output (default '')
6993
6994 Example:
6995
6996 .. literalinclude:: /../../tests/publishers/fixtures/naginator001.yaml
6997 :language: yaml
6998 """
6999 naginator = XML.SubElement(
7000 xml_parent, "com.chikli.hudson.plugin.naginator.NaginatorPublisher"
7001 )
7002 XML.SubElement(naginator, "regexpForRerun").text = str(
7003 data.get("regular-expression", "")
7004 )
7005 XML.SubElement(naginator, "checkRegexp").text = str(
7006 "regular-expression" in data
7007 ).lower()
7008 XML.SubElement(naginator, "rerunIfUnstable").text = str(
7009 data.get("rerun-unstable-builds", False)
7010 ).lower()
7011 XML.SubElement(naginator, "rerunMatrixPart").text = str(
7012 data.get("rerun-matrix-part", False)
7013 ).lower()
7014 progressive_delay = (
7015 "progressive-delay-increment" in data or "progressive-delay-maximum" in data
7016 )
7017 if "fixed-delay" in data and progressive_delay:
7018 raise JenkinsJobsException(
7019 "You cannot specify both fixed " "and progressive delays"
7020 )
7021 if not progressive_delay:
7022 delay = XML.SubElement(
7023 naginator,
7024 "delay",
7025 {"class": "com.chikli.hudson.plugin.naginator.FixedDelay"},
7026 )
7027 XML.SubElement(delay, "delay").text = str(data.get("fixed-delay", "0"))
7028 else:
7029 delay = XML.SubElement(
7030 naginator,
7031 "delay",
7032 {"class": "com.chikli.hudson.plugin.naginator.ProgressiveDelay"},
7033 )
7034 XML.SubElement(delay, "increment").text = str(
7035 data.get("progressive-delay-increment", "0")
7036 )
7037 XML.SubElement(delay, "max").text = str(
7038 data.get("progressive-delay-maximum", "0")
7039 )
7040 XML.SubElement(naginator, "maxSchedule").text = str(
7041 data.get("max-failed-builds", "0")
7042 )
7043
7044
7045 def disable_failed_job(registry, xml_parent, data):
7046 """yaml: disable-failed-job
7047 Automatically disable failed jobs.
7048
7049 Requires the Jenkins :jenkins-plugins:`Disable Failed Job Plugin
7050 <disable-failed-job>`.
7051
7052 :arg str when-to-disable: The condition to disable the job. (required)
7053 Possible values are
7054
7055 * **Only Failure**
7056 * **Failure and Unstable**
7057 * **Unstable**
7058
7059 :arg int no-of-failures: Number of consecutive failures to disable the
7060 job. (optional)
7061
7062 Example:
7063
7064 .. literalinclude::
7065 /../../tests/publishers/fixtures/disable-failed-job001.yaml
7066 :language: yaml
7067 """
7068
7069 xml_element = XML.SubElement(
7070 xml_parent,
7071 "disableFailedJob." "disableFailedJob.DisableFailedJob",
7072 {"plugin": "disable-failed-job"},
7073 )
7074
7075 valid_conditions = ["Only Failure", "Failure and Unstable", "Only Unstable"]
7076 mapping = [("when-to-disable", "whenDisable", None, valid_conditions)]
7077 helpers.convert_mapping_to_xml(xml_element, data, mapping, fail_required=True)
7078
7079 if "no-of-failures" in data:
7080 mapping = [
7081 ("no-of-failures", "failureTimes", None),
7082 ("", "optionalBrockChecked", True),
7083 ]
7084 helpers.convert_mapping_to_xml(xml_element, data, mapping, fail_required=True)
7085 else:
7086 XML.SubElement(xml_element, "optionalBrockChecked").text = "false"
7087
7088
7089 def google_cloud_storage(registry, xml_parent, data):
7090 """yaml: google-cloud-storage
7091 Upload build artifacts to Google Cloud Storage. Requires the
7092 Jenkins :jenkins-plugins:`Google Cloud Storage plugin
7093 <google-storage-plugin>`.
7094
7095 Apart from the Google Cloud Storage Plugin itself, installation of Google
7096 OAuth Credentials and addition of required credentials to Jenkins is
7097 required.
7098
7099 :arg str credentials-id: The set of Google credentials registered with
7100 the Jenkins Credential Manager for authenticating
7101 with your project. (required)
7102 :arg list uploads:
7103 :uploads:
7104 * **expiring-elements** (`dict`)
7105 :params:
7106 * **bucket-name** (`str`) bucket name to upload artifacts
7107 (required)
7108 * **days-to-retain** (`int`) days to keep artifacts
7109 (required)
7110 * **build-log** (`dict`)
7111 :params:
7112 * **log-name** (`str`) name of the file that the Jenkins
7113 console log to be named (required)
7114 * **storage-location** (`str`) bucket name to upload
7115 artifacts (required)
7116 * **share-publicly** (`bool`) whether to share uploaded
7117 share uploaded artifacts with everyone (default false)
7118 * **upload-for-failed-jobs** (`bool`) whether to upload
7119 artifacts even if the build fails (default false)
7120 * **show-inline** (`bool`) whether to show uploaded build
7121 log inline in web browsers, rather than forcing it to be
7122 downloaded (default true)
7123 * **strip-prefix** (`str`) strip this prefix off the
7124 file names (default not set)
7125
7126 * **classic** (`dict`)
7127 :params:
7128 * **file-pattern** (`str`) ant style globs to match the
7129 files to upload (required)
7130 * **storage-location** (`str`) bucket name to upload
7131 artifacts (required)
7132 * **share-publicly** (`bool`) whether to share uploaded
7133 share uploaded artifacts with everyone (default false)
7134 * **upload-for-failed-jobs** (`bool`) whether to upload
7135 artifacts even if the build fails (default false)
7136 * **show-inline** (`bool`) whether to show uploaded
7137 artifacts inline in web browsers, rather than forcing
7138 them to be downloaded (default false)
7139 * **strip-prefix** (`str`) strip this prefix off the
7140 file names (default not set)
7141
7142 Example:
7143
7144 .. literalinclude::
7145 /../../tests/publishers/fixtures/google_cloud_storage001.yaml
7146 :language: yaml
7147
7148 Full example:
7149
7150 .. literalinclude::
7151 /../../tests/publishers/fixtures/google_cloud_storage002.yaml
7152 :language: yaml
7153 """
7154
7155 def expiring_elements(properties, upload_element, types):
7156 # Handle expiring elements upload action
7157
7158 xml_element = XML.SubElement(
7159 upload_element,
7160 "com.google." "jenkins.plugins.storage." "ExpiringBucketLifecycleManager",
7161 )
7162 mapping = [
7163 ("bucket-name", "bucketNameWithVars", None),
7164 ("", "sharedPublicly", False),
7165 ("", "forFailedJobs", False),
7166 ("days-to-retain", "bucketObjectTTL", None),
7167 ]
7168 helpers.convert_mapping_to_xml(
7169 xml_element, properties, mapping, fail_required=True
7170 )
7171
7172 if types.count("expiring-elements") > 1:
7173 XML.SubElement(
7174 xml_element,
7175 "module",
7176 {
7177 "reference": "../../com.google.jenkins.plugins."
7178 "storage.ExpiringBucketLifecycleManager/module"
7179 },
7180 )
7181 else:
7182 XML.SubElement(xml_element, "module")
7183
7184 def build_log(properties, upload_element, types):
7185 # Handle build log upload action
7186
7187 xml_element = XML.SubElement(
7188 upload_element, "com.google.jenkins." "plugins.storage.StdoutUpload"
7189 )
7190 mapping = [
7191 ("storage-location", "bucketNameWithVars", None),
7192 ("share-publicly", "sharedPublicly", False),
7193 ("upload-for-failed-jobs", "forFailedJobs", False),
7194 ("show-inline", "showInline", True),
7195 ("strip-prefix", "pathPrefix", ""),
7196 ("log-name", "logName", None),
7197 ]
7198 helpers.convert_mapping_to_xml(
7199 xml_element, properties, mapping, fail_required=True
7200 )
7201
7202 if types.count("build-log") > 1:
7203 XML.SubElement(
7204 xml_element,
7205 "module",
7206 {
7207 "reference": "../../com.google.jenkins.plugins."
7208 "storage.StdoutUpload/module"
7209 },
7210 )
7211 else:
7212 XML.SubElement(xml_element, "module")
7213
7214 def classic(properties, upload_element, types):
7215 # Handle classic upload action
7216
7217 xml_element = XML.SubElement(
7218 upload_element, "com.google.jenkins." "plugins.storage.ClassicUpload"
7219 )
7220 mapping = [
7221 ("storage-location", "bucketNameWithVars", None),
7222 ("share-publicly", "sharedPublicly", False),
7223 ("upload-for-failed-jobs", "forFailedJobs", False),
7224 ("show-inline", "showInline", False),
7225 ("strip-prefix", "pathPrefix", ""),
7226 ("file-pattern", "sourceGlobWithVars", None),
7227 ]
7228 helpers.convert_mapping_to_xml(
7229 xml_element, properties, mapping, fail_required=True
7230 )
7231
7232 if types.count("classic") > 1:
7233 XML.SubElement(
7234 xml_element,
7235 "module",
7236 {
7237 "reference": "../../com.google.jenkins.plugins."
7238 "storage.ClassicUpload/module"
7239 },
7240 )
7241 else:
7242 XML.SubElement(xml_element, "module")
7243
7244 uploader = XML.SubElement(
7245 xml_parent,
7246 "com.google.jenkins.plugins.storage." "GoogleCloudStorageUploader",
7247 {"plugin": "google-storage-plugin"},
7248 )
7249
7250 mapping = [("credentials-id", "credentialsId", None)]
7251 helpers.convert_mapping_to_xml(uploader, data, mapping, fail_required=True)
7252
7253 valid_upload_types = ["expiring-elements", "build-log", "classic"]
7254 types = []
7255
7256 upload_element = XML.SubElement(uploader, "uploads")
7257
7258 uploads = data["uploads"]
7259 for upload in uploads:
7260 for upload_type, properties in upload.items():
7261 types.append(upload_type)
7262
7263 if upload_type not in valid_upload_types:
7264 raise InvalidAttributeError("uploads", upload_type, valid_upload_types)
7265 else:
7266 locals()[upload_type.replace("-", "_")](
7267 properties, upload_element, types
7268 )
7269
7270
7271 def flowdock(registry, xml_parent, data):
7272 """yaml: flowdock
7273 This plugin publishes job build results to a Flowdock flow.
7274
7275 Requires the Jenkins :jenkins-plugins:`Flowdock Plugin
7276 <jenkins-flowdock-plugin>`.
7277
7278 :arg str token: API token for the targeted flow.
7279 (required)
7280 :arg str tags: Comma-separated list of tags to include in message
7281 (default "")
7282 :arg bool chat-notification: Send chat notification when build fails
7283 (default true)
7284 :arg bool notify-success: Send notification on build success
7285 (default true)
7286 :arg bool notify-failure: Send notification on build failure
7287 (default true)
7288 :arg bool notify-fixed: Send notification when build is fixed
7289 (default true)
7290 :arg bool notify-unstable: Send notification when build is unstable
7291 (default false)
7292 :arg bool notify-aborted: Send notification when build was aborted
7293 (default false)
7294 :arg bool notify-notbuilt: Send notification when build did not occur
7295 (default false)
7296
7297 Example:
7298
7299 .. literalinclude:: /../../tests/publishers/fixtures/flowdock001.yaml
7300 :language: yaml
7301
7302 Full example:
7303
7304 .. literalinclude:: /../../tests/publishers/fixtures/flowdock002.yaml
7305 :language: yaml
7306 """
7307
7308 def gen_notification_entry(data_item, default, text):
7309 e = XML.SubElement(nm, "entry")
7310 mapping = [
7311 ("", "com.flowdock.jenkins.BuildResult", text),
7312 (data_item, "boolean", default),
7313 ]
7314 helpers.convert_mapping_to_xml(e, data, mapping, fail_required=True)
7315
7316 parent = XML.SubElement(xml_parent, "com.flowdock.jenkins.FlowdockNotifier")
7317 mapping = [
7318 ("token", "flowToken", None),
7319 ("tags", "notificationTags", ""),
7320 ("chat-notification", "chatNotification", True),
7321 ("notify-success", "notifySuccess", True),
7322 ("notify-failure", "notifyFailure", True),
7323 ("notify-fixed", "notifyFixed", True),
7324 ("notify-unstable", "notifyUnstable", False),
7325 ("notify-aborted", "notifyAborted", False),
7326 ("notify-notbuilt", "notifyNotBuilt", False),
7327 ]
7328 helpers.convert_mapping_to_xml(parent, data, mapping, fail_required=True)
7329
7330 nm = XML.SubElement(parent, "notifyMap")
7331
7332 # notification entries
7333 gen_notification_entry("notify-success", True, "SUCCESS")
7334 gen_notification_entry("notify-failure", True, "FAILURE")
7335 gen_notification_entry("notify-fixed", True, "FIXED")
7336 gen_notification_entry("notify-unstable", False, "UNSTABLE")
7337 gen_notification_entry("notify-aborted", False, "ABORTED")
7338 gen_notification_entry("notify-notbuilt", False, "NOT_BUILT")
7339
7340
7341 def clamav(registry, xml_parent, data):
7342 """yaml: clamav
7343 Check files with ClamAV, an open source antivirus engine.
7344 Requires the Jenkins :jenkins-plugins:`ClamAV Plugin <clamav>`.
7345
7346 :arg str includes: Comma separated list of files that should be scanned.
7347 Must be set for ClamAV to check for artifacts. (default '')
7348 :arg str excludes: Comma separated list of files that should be ignored
7349 (default '')
7350
7351 Full Example:
7352
7353 .. literalinclude:: /../../tests/publishers/fixtures/clamav-full.yaml
7354 :language: yaml
7355
7356 Minimal Example:
7357
7358 .. literalinclude:: /../../tests/publishers/fixtures/clamav-minimal.yaml
7359 :language: yaml
7360 """
7361 clamav = XML.SubElement(xml_parent, "org.jenkinsci.plugins.clamav.ClamAvRecorder")
7362 clamav.set("plugin", "clamav")
7363
7364 mappings = [("includes", "includes", ""), ("excludes", "excludes", "")]
7365 helpers.convert_mapping_to_xml(clamav, data, mappings, fail_required=True)
7366
7367
7368 def testselector(registry, xml_parent, data):
7369 """yaml: testselector
7370 This plugin allows you to choose specific tests you want to run.
7371
7372 Requires the Jenkins :jenkins-plugins:`Tests Selector Plugin
7373 <selected-tests-executor>`.
7374
7375 :arg str name: Environment variable in which selected tests are saved
7376 (required)
7377 :arg str description: Description
7378 (default "")
7379 :arg str properties-file: Contain all your tests
7380 (required)
7381 :arg str enable-field: Imply if the test is enabled or not
7382 (default "")
7383 :arg str groupby: Plugin will group the tests by
7384 (default "")
7385 :arg str field-sperator: Separate between the fields in the tests tree
7386 (default "")
7387 :arg str show-fields: Shown in the tests tree
7388 (default "")
7389 :arg str multiplicity-field: Number of times the test should run
7390 (default "")
7391
7392 Example:
7393
7394 .. literalinclude:: /../../tests/publishers/fixtures/testselector001.yaml
7395 :language: yaml
7396 """
7397
7398 testselector = XML.SubElement(
7399 xml_parent, "il.ac.technion.jenkins.plugins" "TestExecuter"
7400 )
7401
7402 mapping = [
7403 ("name", "name", None),
7404 ("description", "description", ""),
7405 ("properties-file", "propertiesFilePath", None),
7406 ("enable-field", "enableField", ""),
7407 ("groupby", "groupBy", ""),
7408 ("field-separator", "fieldSeparator", ""),
7409 ("show-fields", "showFields", ""),
7410 ("multiplicity-field", "multiplicityField", ""),
7411 ]
7412 helpers.convert_mapping_to_xml(testselector, data, mapping, fail_required=True)
7413
7414
7415 def cloudformation(registry, xml_parent, data):
7416 """yaml: cloudformation
7417 Create cloudformation stacks before running a build and optionally
7418 delete them at the end. Requires the Jenkins :jenkins-plugins:`AWS
7419 Cloudformation Plugin <jenkins-cloudformation-plugin>`.
7420
7421 :arg list create-stacks: List of stacks to create
7422
7423 :create-stacks attributes:
7424 * **arg str name** - The name of the stack (Required)
7425 * **arg str description** - Description of the stack (Optional)
7426 * **arg str recipe** - The cloudformation recipe file (Required)
7427 * **arg list parameters** - A list of key/value pairs, will be
7428 joined together into a comma separated string (Optional)
7429 * **arg int timeout** - Number of seconds to wait before giving up
7430 creating a stack (default 0)
7431 * **arg str access-key** - The Amazon API Access Key (Required)
7432 * **arg str secret-key** - The Amazon API Secret Key (Required)
7433 * **arg int sleep** - Number of seconds to wait before continuing
7434 to the next step (default 0)
7435 * **arg array region** - The region to run cloudformation in.
7436 (Required)
7437
7438 :region values:
7439 * **us-east-1**
7440 * **us-west-1**
7441 * **us-west-2**
7442 * **eu-central-1**
7443 * **eu-west-1**
7444 * **ap-southeast-1**
7445 * **ap-southeast-2**
7446 * **ap-northeast-1**
7447 * **sa-east-1**
7448 :arg list delete-stacks: List of stacks to delete
7449
7450 :delete-stacks attributes:
7451 * **arg list name** - The names of the stacks to delete (Required)
7452 * **arg str access-key** - The Amazon API Access Key (Required)
7453 * **arg str secret-key** - The Amazon API Secret Key (Required)
7454 * **arg bool prefix** - If selected the tear down process will look
7455 for the stack that Starts with the stack name with the oldest
7456 creation date and will delete it. (default false)
7457 * **arg array region** - The region to run cloudformation in.
7458 (Required)
7459
7460 :region values:
7461 * **us-east-1**
7462 * **us-west-1**
7463 * **us-west-2**
7464 * **eu-central-1**
7465 * **eu-west-1**
7466 * **ap-southeast-1**
7467 * **ap-southeast-2**
7468 * **ap-northeast-1**
7469 * **sa-east-1**
7470
7471 Example:
7472
7473 .. literalinclude:: /../../tests/publishers/fixtures/cloudformation.yaml
7474 :language: yaml
7475 """
7476 region_dict = helpers.cloudformation_region_dict()
7477 stacks = helpers.cloudformation_init(
7478 xml_parent, data, "CloudFormationPostBuildNotifier"
7479 )
7480 for stack in data.get("create-stacks", []):
7481 helpers.cloudformation_stack(
7482 xml_parent, stack, "PostBuildStackBean", stacks, region_dict
7483 )
7484 delete_stacks = helpers.cloudformation_init(
7485 xml_parent, data, "CloudFormationNotifier"
7486 )
7487 for delete_stack in data.get("delete-stacks", []):
7488 helpers.cloudformation_stack(
7489 xml_parent, delete_stack, "SimpleStackBean", delete_stacks, region_dict
7490 )
7491
7492
7493 def whitesource(registry, xml_parent, data):
7494 """yaml: whitesource
7495 This plugin brings automatic open source management to Jenkins users.
7496
7497 Requires the Jenkins :jenkins-plugins:`Whitesource Plugin
7498 <whitesource>`.
7499
7500 :arg str product-token: Product name or token to update (default '')
7501 :arg str version: Product version (default '')
7502 :arg str override-token: Override the api token from the global config
7503 (default '')
7504 :arg str project-token: Token uniquely identifying the project to update
7505 (default '')
7506 :arg list includes: list of libraries to include (default '[]')
7507 :arg list excludes: list of libraries to exclude (default '[]')
7508 :arg str policies: Whether to override the global settings. Valid values:
7509 global, enable, disable (default 'global')
7510 :arg str requester-email: Email of the WhiteSource user that requests to
7511 update WhiteSource (>=1.5.1) (default '')
7512
7513 Full Example:
7514
7515 .. literalinclude:: /../../tests/publishers/fixtures/whitesource-full.yaml
7516 :language: yaml
7517
7518 Minimal Example:
7519
7520 .. literalinclude::
7521 /../../tests/publishers/fixtures/whitesource-minimal.yaml
7522 :language: yaml
7523 """
7524 whitesource = XML.SubElement(
7525 xml_parent, "org.whitesource.jenkins." "WhiteSourcePublisher"
7526 )
7527 whitesource.set("plugin", "whitesource")
7528 policies = ["global", "enable", "disable"]
7529
7530 mappings = [
7531 ("policies", "jobCheckPolicies", "global", policies),
7532 ("override-token", "jobApiToken", ""),
7533 ("product-token", "product", ""),
7534 ("version", "productVersion", ""),
7535 ("project-token", "projectToken", ""),
7536 ("requester-email", "requesterEmail", ""),
7537 ]
7538 helpers.convert_mapping_to_xml(whitesource, data, mappings, fail_required=True)
7539
7540 XML.SubElement(whitesource, "libIncludes").text = " ".join(data.get("includes", []))
7541 XML.SubElement(whitesource, "libExcludes").text = " ".join(data.get("excludes", []))
7542 XML.SubElement(whitesource, "ignorePomModules").text = "false"
7543
7544
7545 def hipchat(registry, xml_parent, data):
7546 """yaml: hipchat
7547 Publisher that sends hipchat notifications on job events
7548 Requires the Jenkins :jenkins-plugins:`Hipchat Plugin
7549 <hipchat>` version >=1.9
7550
7551 Please see documentation for older plugin version
7552 https://jenkins-job-builder.readthedocs.io/en/latest/hipchat.html
7553
7554 :arg str token: This will override the default auth token (optional)
7555 :arg list rooms: list of HipChat rooms to post messages to, overrides
7556 global default (optional)
7557 :arg bool notify-start: post messages about build start event
7558 (default false)
7559 :arg bool notify-success: post messages about successful build event
7560 (default false)
7561 :arg bool notify-aborted: post messages about aborted build event
7562 (default false)
7563 :arg bool notify-not-built: post messages about build set to NOT_BUILT.
7564 This status code is used in a multi-stage build where a problem in
7565 earlier stage prevented later stages from building. (default false)
7566 :arg bool notify-unstable: post messages about unstable build event
7567 (default false)
7568 :arg bool notify-failure: post messages about build failure event
7569 (default false)
7570 :arg bool notify-back-to-normal: post messages about build being back to
7571 normal after being unstable or failed (default false)
7572 :arg str start-message: This will override the default start message
7573 (optional)
7574 :arg str complete-message: This will override the default complete message
7575 (optional)
7576
7577 Example:
7578
7579 .. literalinclude:: /../../tests/publishers/fixtures/hipchat001.yaml
7580 :language: yaml
7581 """
7582 hipchat = XML.SubElement(xml_parent, "jenkins.plugins.hipchat.HipChatNotifier")
7583 XML.SubElement(hipchat, "token").text = str(data.get("token", ""))
7584
7585 if "rooms" in data:
7586 XML.SubElement(hipchat, "room").text = str(",".join(data["rooms"]))
7587
7588 mapping = [
7589 ("notify-start", "startNotification", False),
7590 ("notify-success", "notifySuccess", False),
7591 ("notify-aborted", "notifyAborted", False),
7592 ("notify-not-built", "notifyNotBuilt", False),
7593 ("notify-unstable", "notifyUnstable", False),
7594 ("notify-failure", "notifyFailure", False),
7595 ("notify-back-to-normal", "notifyBackToNormal", False),
7596 ("start-message", "startJobMessage", None),
7597 ("complete-message", "completeJobMessage", None),
7598 ]
7599 helpers.convert_mapping_to_xml(hipchat, data, mapping, fail_required=False)
7600
7601
7602 def slack(registry, xml_parent, data):
7603 """yaml: slack
7604 Publisher that sends slack notifications on job events.
7605
7606 Requires the Jenkins :jenkins-plugins:`Slack Plugin <slack>`
7607
7608 When using Slack Plugin version < 2.0, Slack Plugin itself requires a
7609 publisher as well as properties please note that you have to create those
7610 too. When using Slack Plugin version >= 2.0, you should only configure the
7611 publisher.
7612
7613 For backward compatibility, the publisher needs to query version of the
7614 Slack Plugin. Hence the ``query_plugins_info`` parameter shouldn't be set
7615 to ``False`` in the ``jenkins`` section of the configuration file.
7616
7617 :arg str team-domain: Your team's domain at slack. (default '')
7618 :arg str auth-token: The integration token to be used when sending
7619 notifications. (default '')
7620 :arg str auth-token-id: Allows credentials to be stored in Jenkins.
7621 (default '')
7622 :arg str build-server-url: Specify the URL for your server installation.
7623 (default '/')
7624 :arg str room: A comma separated list of rooms / channels to post the
7625 notifications to. (default '')
7626 :arg bool notify-start: Send notification when the job starts (>=2.0).
7627 (default false)
7628 :arg bool notify-success: Send notification on success (>=2.0).
7629 (default false)
7630 :arg bool notify-aborted: Send notification when job is aborted (>=2.0).
7631 (default false)
7632 :arg bool notify-not-built: Send notification when job set to NOT_BUILT
7633 status (>=2.0). (default false)
7634 :arg bool notify-unstable: Send notification when job becomes unstable
7635 (>=2.0). (default false)
7636 :arg bool notify-failure: Send notification when job fails for the first
7637 time (previous build was a success) (>=2.0). (default false)
7638 :arg bool notify-every-failure: Send notification every time a job fails
7639 (>=2.23). (default false)
7640 :arg bool notify-back-to-normal: Send notification when job is succeeding
7641 again after being unstable or failed (>=2.0). (default false)
7642 :arg bool notify-repeated-failure: Send notification when job fails
7643 successively (previous build was also a failure) (>=2.0).
7644 (default false)
7645 :arg bool notify-regression: Send notification when number of failed tests
7646 increased or the failed tests are different than previous build
7647 (>=2.2). (default false)
7648 :arg bool include-failed-tests: includes all failed tests when some tests
7649 failed. does nothing if no failed tests were found (>=2.2).
7650 (default false)
7651 :arg bool include-test-summary: Include the test summary (>=2.0).
7652 (default false)
7653 :arg str commit-info-choice: What commit information to include into
7654 notification message, "NONE" includes nothing about commits, "AUTHORS"
7655 includes commit list with authors only, and "AUTHORS_AND_TITLES"
7656 includes commit list with authors and titles (>=2.0). (default "NONE")
7657 :arg bool include-custom-message: Include a custom message into the
7658 notification (>=2.0). (default false)
7659 :arg str custom-message: Custom message to be included for all statuses
7660 (>=2.0). (default '')
7661 :arg str custom-message-success: Custom message for succesful builds
7662 (>=2.10). (default '')
7663 :arg str custom-message-aborted: Custom message for aborted builds
7664 (>=2.10). (default '')
7665 :arg str custom-message-not-built: Custom message for not-built
7666 (>=2.10). (default '')
7667 :arg str custom-message-unstable: Custom message for unstable builds
7668 (>=2.10). (default '')
7669 :arg str custom-message-failure: Custom message for failed builds
7670 (>=2.10). (default '')
7671 :arg str auth-token-credential-id: The ID for the integration token from
7672 the Credentials plugin to be used to send notifications to Slack.
7673 (>=2.1) (default '')
7674 :arg bool bot-user: This option indicates the token belongs to a bot user
7675 in Slack. (>=2.2) (default False)
7676 :arg str base-url: Your Slack compatible Base URL. ``bot-user`` is not
7677 supported with Base URL. (>=2.2) (default '')
7678
7679 Example (version < 2.0):
7680
7681 .. literalinclude::
7682 /../../tests/publishers/fixtures/slack001.yaml
7683 :language: yaml
7684
7685 Minimal example (version >= 2.0):
7686
7687 .. literalinclude::
7688 /../../tests/publishers/fixtures/slack003.yaml
7689 :language: yaml
7690
7691 Full example (version >= 2.10):
7692
7693 .. literalinclude::
7694 /../../tests/publishers/fixtures/slack005.yaml
7695 :language: yaml
7696
7697 """
7698
7699 def _add_xml(elem, name, value=""):
7700 if isinstance(value, bool):
7701 value = str(value).lower()
7702 XML.SubElement(elem, name).text = value
7703
7704 logger = logging.getLogger(__name__)
7705
7706 plugin_ver = registry.get_plugin_version("Slack Notification Plugin")
7707
7708 mapping = (
7709 ("team-domain", "teamDomain", ""),
7710 ("auth-token", "authToken", ""),
7711 ("auth-token-id", "authTokenCredentialId", ""),
7712 ("build-server-url", "buildServerUrl", "/"),
7713 ("room", "room", ""),
7714 )
7715 mapping_20 = (
7716 ("notify-start", "startNotification", False),
7717 ("notify-success", "notifySuccess", False),
7718 ("notify-aborted", "notifyAborted", False),
7719 ("notify-not-built", "notifyNotBuilt", False),
7720 ("notify-unstable", "notifyUnstable", False),
7721 ("notify-failure", "notifyFailure", False),
7722 ("notify-every-failure", "notifyEveryFailure", False),
7723 ("notify-back-to-normal", "notifyBackToNormal", False),
7724 ("notify-regression", "notifyRegression", False),
7725 ("notify-repeated-failure", "notifyRepeatedFailure", False),
7726 ("include-test-summary", "includeTestSummary", False),
7727 ("include-failed-tests", "includeFailedTests", False),
7728 ("commit-info-choice", "commitInfoChoice", "NONE"),
7729 ("include-custom-message", "includeCustomMessage", False),
7730 ("custom-message", "customMessage", ""),
7731 ("custom-message-success", "customMessageSuccess", ""),
7732 ("custom-message-aborted", "customMessageAborted", ""),
7733 ("custom-message-not-built", "customMessageNotBuilt", ""),
7734 ("custom-message-unstable", "customMessageUnstable", ""),
7735 ("custom-message-failure", "customMessageFailure", ""),
7736 ("auth-token-credential-id", "authTokenCredentialId", ""),
7737 ("bot-user", "botUser", False),
7738 ("base-url", "baseUrl", ""),
7739 )
7740
7741 commit_info_choices = ["NONE", "AUTHORS", "AUTHORS_AND_TITLES"]
7742
7743 slack = XML.SubElement(xml_parent, "jenkins.plugins.slack.SlackNotifier")
7744
7745 if plugin_ver >= "2.0":
7746 mapping = mapping + mapping_20
7747
7748 if plugin_ver < "2.0":
7749 for yaml_name, _, default_value in mapping:
7750 # All arguments that don't have a default value are mandatory for
7751 # the plugin to work as intended.
7752 if not data.get(yaml_name, default_value):
7753 raise MissingAttributeError(yaml_name)
7754
7755 for yaml_name, _, _ in mapping_20:
7756 if yaml_name in data:
7757 logger.warning(
7758 "'%s' is invalid with plugin version < 2.0, ignored", yaml_name
7759 )
7760
7761 for yaml_name, xml_name, default_value in mapping:
7762 value = data.get(yaml_name, default_value)
7763
7764 # 'commit-info-choice' is enumerated type
7765 if yaml_name == "commit-info-choice" and value not in commit_info_choices:
7766 raise InvalidAttributeError(yaml_name, value, commit_info_choices)
7767
7768 # Ensure that custom-message is set when include-custom-message is set
7769 # to true.
7770 if (
7771 yaml_name == "include-custom-message"
7772 and data is False
7773 and not data.get("custom-message", "")
7774 ):
7775 raise MissingAttributeError("custom-message")
7776
7777 _add_xml(slack, xml_name, value)
7778
7779
7780 def phabricator(registry, xml_parent, data):
7781 """yaml: phabricator
7782 Integrate with `Phabricator <https://www.phacility.com/>`_
7783
7784 Requires the Jenkins :jenkins-plugins:`Phabricator Plugin
7785 <phabricator-plugin>`.
7786
7787 :arg bool comment-on-success: Post a *comment* when the build
7788 succeeds. (optional)
7789 :arg bool uberalls-enabled: Integrate with uberalls. (optional)
7790 :arg str comment-file: Include contents of given file if
7791 commenting is enabled. (optional)
7792 :arg int comment-size: Maximum comment character length. (optional)
7793 :arg bool comment-with-console-link-on-failure: Post a *comment*
7794 when the build fails. (optional)
7795
7796 Example:
7797
7798 .. literalinclude::
7799 /../../tests/publishers/fixtures/phabricator001.yaml
7800 :language: yaml
7801 """
7802
7803 root = XML.SubElement(
7804 xml_parent, "com.uber.jenkins.phabricator.PhabricatorNotifier"
7805 )
7806 mapping = [
7807 ("comment-on-success", "commentOnSuccess", None),
7808 ("uberalls-enabled", "uberallsEnabled", None),
7809 ("comment-file", "commentFile", None),
7810 ("comment-size", "commentSize", None),
7811 (
7812 "comment-with-console-link-on-failure",
7813 "commentWithConsoleLinkOnFailure",
7814 None,
7815 ),
7816 ]
7817 helpers.convert_mapping_to_xml(root, data, mapping, fail_required=False)
7818
7819
7820 def jms_messaging(registry, xml_parent, data):
7821 """yaml: jms-messaging
7822 The JMS Messaging Plugin provides the following functionality:
7823 - A build trigger to submit jenkins jobs upon receipt
7824 of a matching message.
7825 - A builder that may be used to submit a message to the topic
7826 upon the completion of a job
7827 - A post-build action that may be used to submit a message to the topic
7828 upon the completion of a job
7829
7830
7831 JMS Messaging provider types supported:
7832 - ActiveMQ
7833 - FedMsg
7834
7835 Requires the Jenkins :jenkins-plugins:`JMS Messaging Plugin
7836 Pipeline Plugin <jms-messaging>`.
7837
7838 :arg str override-topic: If you need to override the default topic.
7839 (default '')
7840 :arg str provider-name: Name of message provider setup in the
7841 global config. (default '')
7842 :arg str msg-type: A message type
7843 (default 'CodeQualityChecksDone')
7844 :arg str msg-props: Message header to publish. (default '')
7845 :arg str msg-content: Message body to publish. (default '')
7846
7847
7848 Full Example:
7849
7850 .. literalinclude::
7851 ../../tests/publishers/fixtures/jms-messaging-full.yaml
7852 :language: yaml
7853
7854 Minimal Example:
7855
7856 .. literalinclude::
7857 ../../tests/publishers/fixtures/jms-messaging-minimal.yaml
7858 :language: yaml
7859 """
7860 helpers.jms_messaging_common(
7861 xml_parent, "com.redhat.jenkins.plugins.ci." "CIMessageNotifier", data
7862 )
7863
7864
7865 def openshift_build_canceller(registry, xml_parent, data):
7866 r"""yaml: openshift-build-canceller
7867 This action is intended to provide cleanup for a Jenkins job which failed
7868 because a build is hung (instead of terminating with a failure code);
7869 this step will allow you to perform the equivalent of a oc cancel-build
7870 for the provided build config; any builds under that build config which
7871 are not previously terminated (either successfully or unsuccessfully)
7872 or cancelled will be cancelled.
7873
7874 Requires the Jenkins :jenkins-plugins:`OpenShift Pipeline Plugin
7875 <openshift-pipeline>`.
7876
7877 :arg str api-url: this would be the value you specify if you leverage the
7878 --server option on the OpenShift `oc` command.
7879 (default '\https://openshift.default.svc.cluster.local')
7880 :arg str bld-cfg: The value here should be whatever was the output
7881 form `oc project` when you created the BuildConfig you
7882 want to run a Build on (default 'frontend')
7883 :arg str namespace: If you run `oc get bc` for the project listed in
7884 "namespace", that is the value you want to put here. (default 'test')
7885 :arg str auth-token: The value here is what you supply with the --token
7886 option when invoking the OpenShift `oc` command. (default '')
7887 :arg bool verbose: This flag is the toggle for
7888 turning on or off detailed logging in this plug-in. (default false)
7889
7890 Full Example:
7891
7892 .. literalinclude::
7893 ../../tests/publishers/fixtures/openshift-build-canceller001.yaml
7894 :language: yaml
7895
7896 Minimal Example:
7897
7898 .. literalinclude::
7899 ../../tests/publishers/fixtures/openshift-build-canceller002.yaml
7900 :language: yaml
7901 """
7902
7903 osb = XML.SubElement(
7904 xml_parent, "com.openshift.jenkins.plugins.pipeline." "OpenShiftBuildCanceller"
7905 )
7906 mapping = [
7907 # option, xml name, default value
7908 ("api-url", "apiURL", "https://openshift.default.svc.cluster.local"),
7909 ("bld-cfg", "bldCfg", "frontend"),
7910 ("namespace", "namespace", "test"),
7911 ("auth-token", "authToken", ""),
7912 ("verbose", "verbose", False),
7913 ]
7914 helpers.convert_mapping_to_xml(osb, data, mapping, fail_required=True)
7915
7916
7917 def openshift_deploy_canceller(registry, xml_parent, data):
7918 r"""yaml: openshift-deploy-canceller
7919 This action is intended to provide cleanup for any OpenShift deployments
7920 left running when the Job completes; this step will allow you to perform
7921 the equivalent of a oc deploy --cancel for the provided deployment config.
7922
7923 Requires the Jenkins :jenkins-plugins:`OpenShift Pipeline Plugin
7924 <openshift-pipeline>`.
7925
7926 :arg str api-url: this would be the value you specify if you leverage the
7927 --server option on the OpenShift `oc` command.
7928 (default '\https://openshift.default.svc.cluster.local')
7929 :arg str dep-cfg: The value here should be whatever was the output
7930 form `oc project` when you created the BuildConfig you want to run a
7931 Build on (default frontend)
7932 :arg str namespace: If you run `oc get bc` for the project listed in
7933 "namespace", that is the value you want to put here. (default 'test')
7934 :arg str auth-token: The value here is what you supply with the --token
7935 option when invoking the OpenShift `oc` command. (default '')
7936 :arg bool verbose: This flag is the toggle for
7937 turning on or off detailed logging in this plug-in. (default false)
7938
7939 Full Example:
7940
7941 .. literalinclude::
7942 ../../tests/publishers/fixtures/openshift-deploy-canceller001.yaml
7943 :language: yaml
7944
7945 Minimal Example:
7946
7947 .. literalinclude::
7948 ../../tests/publishers/fixtures/openshift-deploy-canceller002.yaml
7949 :language: yaml
7950 """
7951
7952 osb = XML.SubElement(
7953 xml_parent, "com.openshift.jenkins.plugins.pipeline." "OpenShiftDeployCanceller"
7954 )
7955 mapping = [
7956 # option, xml name, default value
7957 ("api-url", "apiURL", "https://openshift.default.svc.cluster.local"),
7958 ("dep-cfg", "depCfg", "frontend"),
7959 ("namespace", "namespace", "test"),
7960 ("auth-token", "authToken", ""),
7961 ("verbose", "verbose", False),
7962 ]
7963 helpers.convert_mapping_to_xml(osb, data, mapping, fail_required=True)
7964
7965
7966 def github_pull_request_merge(registry, xml_parent, data):
7967 """yaml: github-pull-request-merge
7968 This action merges the pull request that triggered the build (see the
7969 github pull request trigger)
7970
7971 Requires the Jenkins :jenkins-plugins:`GitHub pull request builder plugin
7972 <ghprb>`.
7973
7974
7975 :arg bool only-admins-merge: if `true` only administrators can merge the
7976 pull request, (default false)
7977 :arg bool disallow-own-code: if `true` will allow merging your own pull
7978 requests, in opposite to needing someone else to trigger the merge.
7979 (default false)
7980 :arg str merge-comment: Comment to set on the merge commit (default '')
7981 :arg bool fail-on-non-merge: fail the job if the merge was unsuccessful
7982 (default false)
7983 :arg bool delete-on-merge: Delete the branch of the pull request on
7984 successful merge (default false)
7985
7986 Full Example:
7987
7988 .. literalinclude::
7989 ../../tests/publishers/fixtures/github-pull-request-merge001.yaml
7990 :language: yaml
7991
7992 Minimal Example:
7993
7994 .. literalinclude::
7995 ../../tests/publishers/fixtures/github-pull-request-merge002.yaml
7996 :language: yaml
7997 """
7998
7999 osb = XML.SubElement(
8000 xml_parent, "org.jenkinsci.plugins.ghprb.GhprbPullRequestMerge"
8001 )
8002 mapping = [
8003 # option, xml name, default value
8004 ("only-admins-merge", "onlyAdminsMerge", "false"),
8005 ("disallow-own-code", "disallowOwnCode", "false"),
8006 ("merge-comment", "mergeComment", ""),
8007 ("fail-on-non-merge", "failOnNonMerge", "false"),
8008 ("delete-on-merge", "deleteOnMerge", "false"),
8009 ]
8010
8011 helpers.convert_mapping_to_xml(osb, data, mapping, fail_required=True)
8012
8013
8014 def chuck_norris(registry, xml_parent, data):
8015 """yaml: chuck-norris
8016 Displays a picture of Chuck Norris (instead of Jenkins the butler) and a
8017 random Chuck Norris 'The Programmer' fact on each build page.
8018
8019 Requires the Jenkins :jenkins-plugins:`ChuckNorris Plugin <chucknorris>`.
8020
8021 Example:
8022
8023 .. literalinclude:: /../../tests/publishers/fixtures/chuck-norris.yaml
8024 :language: yaml
8025 """
8026
8027 chuck = XML.SubElement(
8028 xml_parent, "hudson.plugins.chucknorris.CordellWalkerRecorder"
8029 )
8030 return XML.SubElement(chuck, "factGenerator")
8031
8032
8033 def publishers_from(registry, xml_parent, data):
8034 """yaml: publishers-from
8035 Use publishers from another project.
8036 Requires the Jenkins :jenkins-plugins:`Template Project Plugin
8037 <template-project>`.
8038
8039 :arg str project-name: The name of the other project.
8040
8041 Example:
8042
8043 .. literalinclude:: ../../tests/publishers/fixtures/publishers-from.yaml
8044 :language: yaml
8045 """
8046 pbs = XML.SubElement(xml_parent, "hudson.plugins.templateproject.ProxyPublisher")
8047 mapping = [("project-name", "projectName", None)]
8048 helpers.convert_mapping_to_xml(pbs, data, mapping, fail_required=True)
8049
8050
8051 def tasks(registry, xml_parent, data):
8052 """yaml: tasks
8053
8054 Scans the workspace files for open tasks and generates a trend report.
8055
8056 Requires the Jenkins Task Scanner Plugin
8057 (:jenkins-github:`tasks-plugin`).
8058
8059 :arg list files-to-scan: Fileset includes setting that specifies the
8060 workspace files to scan for tasks, such as ``**/*.java``. Basedir of
8061 the fileset is the workspace root. (default '``**/*.java``')
8062 :arg list files-to-exclude: Fileset excludes setting that specifies the
8063 workspace files to exclude scanning for tasks, such as library source
8064 files. Basedir of the fileset is the workspace root. (default '')
8065 :arg list tasks-tags-high: Tags identifiers for high priority that should
8066 be looked for in the workspace files. Only alphanumerical characters
8067 are allowed as tags as these strings are pasted into a regular
8068 expression. (default '')
8069 :arg list tasks-tags-normal: Tags identifiers for normal priority that
8070 should be looked for in the workspace files. Only alphanumerical
8071 characters are allowed as tags as these strings are pasted into a
8072 regular expression. (default '')
8073 :arg list tasks-tags-low: Tags identifiers for low priority that should be
8074 looked for in the workspace files. Only alphanumerical characters are
8075 allowed as tags as these strings are pasted into a regular expression.
8076 (default '')
8077 :arg bool ignore-case: Ignore the case of the the tag identifiers. (default
8078 false)
8079 :arg bool regular-expression: Treat the tag identifiers as regular
8080 expression. Note that the regular expression must contain two capturing
8081 groups, the first one is interpreted as tag name, the second one as
8082 message. An example of such a regular expression would be
8083 ``^.*(TODO(?:[0-9]*))(.*)$``. (default false)
8084 :arg bool run-always: By default, this plug-in runs only for stable or
8085 unstable builds, but not for failed builds. If this plug-in should run
8086 even for failed builds then activate this check box. (default false)
8087 :arg bool detect-module: Determines if Ant or Maven modules should be
8088 detected for all files that contain warnings. Activating this option
8089 may increase your build time since the detector scans the whole
8090 workspace for ``build.xml`` or ``pom.xml`` files in order to assign the
8091 correct module names. (default false)
8092 :arg int health-thresholds-100: Configure the upper thresholds for the
8093 build health. If left empty then no health report is created. If the
8094 actual number of warnings is between the provided thresholds then the
8095 build health is interpolated. (default '')
8096 :arg str health-thresholds-0: Configure the lower thresholds for the build
8097 health. If left empty then no health report is created. If the actual
8098 number of warnings is between the provided thresholds then the build
8099 health is interpolated. (default '')
8100 :arg str health-priorities: Determines which warning priorities should be
8101 considered when evaluating the build health. Can be ``high`` (only
8102 priority high), ``normal`` (priorities high and normal) or ``low`` (all
8103 priorities). (default 'low')
8104 :arg dict status-thresholds: Configure the build status and health. If the
8105 number of total or new warnings is greater than one of these thresholds
8106 then a build is considered as unstable or failed, respectively. I.e., a
8107 value of 0 means that the build status is changed if there is at least
8108 one warning found. Leave this field empty if the state of the build
8109 should not depend on the number of warnings. Note that for new
8110 warnings, you need to enable the next option
8111 (``compute-new-warnings``).
8112
8113 :status-thresholds:
8114
8115 * **unstable-total-all** (`str`): Total number for all priorities,
8116 unstable threshold (default '')
8117 * **unstable-total-high** (`str`): Total number for high priority,
8118 unstable threshold (default '')
8119 * **unstable-total-normal** (`str`): Total number for normal
8120 priority, unstable threshold (default '')
8121 * **unstable-total-low** (`str`): Total number for low priority,
8122 unstable threshold (default '')
8123 * **failed-total-all** (`str`): Total number for all priorities,
8124 failure threshold (default '')
8125 * **failed-total-high** (`str`): Total number for high priority,
8126 failure threshold (default '')
8127 * **failed-total-normal** (`str`): Total number for normal
8128 priority, failure threshold (default '')
8129 * **failed-total-low** (`str`): Total number for low priority,
8130 failure threshold (default '')
8131 * **unstable-new-all** (`str`): New number for all priorities,
8132 unstable threshold (default '')
8133 * **unstable-new-high** (`str`): New number for high priority,
8134 unstable threshold (default '')
8135 * **unstable-new-normal** (`str`): New number for normal priority,
8136 unstable threshold (default '')
8137 * **unstable-new-low** (`str`): New number for low priority,
8138 unstable threshold (default '')
8139 * **failed-new-all** (`str`): New number for all priorities,
8140 failure threshold (default '')
8141 * **failed-new-high** (`str`): New number for high priority,
8142 failure threshold (default '')
8143 * **failed-new-normal** (`str`): New number for normal priority,
8144 failure threshold (default '')
8145 * **failed-new-low** (`str`): New number for low priority, failure
8146 threshold (default '')
8147
8148 :arg bool compute-new-warnings: Compute new warnings (based on the last
8149 successful build unless another reference build is chosen below).
8150 (default false)
8151 :arg bool use-delta: If set the number of new warnings is computed by
8152 subtracting the total number of warnings of the reference build from
8153 the total number of warnings of the current build. This may lead to
8154 wrong results if you have both fixed and new warnings in a build. If
8155 unset the number of new warnings is computed by a more sophisticated
8156 algorithm: instead of using totals an asymmetric set difference of the
8157 warnings in the current build and the warnings in the reference build
8158 is used. This will find all new warnings even if the number of total
8159 warnings has decreased. Note that sometimes false positives will be
8160 reported due to minor changes in a warning (e.g. refactoring of
8161 variables or method names). It is recommended to uncheck this option in
8162 order to get the most accurate results for new warnings. Depends on
8163 ``compute-new-warnings`` option. (default false)
8164 :arg bool use-prev-build-as-ref: If set the number of new warnings will
8165 always be computed based on the previous build, even if that build is
8166 unstable (due to a violated warning threshold). Otherwise the last
8167 build that did not violate any given threshold will be used as
8168 reference. It is recommended to uncheck this option if the plug-in
8169 should ensure that all new warnings will be finally fixed in subsequent
8170 builds. Depends on ``compute-new-warnings`` option. (default false)
8171 :arg bool only-use-stable-as-ref: Use the last stable build as the
8172 reference to compute the number of new warnings against. This allows
8173 you to ignore interim unstable builds for which the number of warnings
8174 decreased. Note that the last stable build is evaluated only by
8175 inspecting the unit test failures. The static analysis results are not
8176 considered. Depends on ``compute-new-warnings`` option. (default false)
8177 :arg str default-encoding: Default encoding when parsing or showing files.
8178 Leave this field empty to use the default encoding of the platform.
8179 (default '')
8180
8181 Minimal Example:
8182
8183 .. literalinclude:: /../../tests/publishers/fixtures/tasks-minimal.yaml
8184 :language: yaml
8185
8186 Full Example:
8187
8188 .. literalinclude:: /../../tests/publishers/fixtures/tasks-full.yaml
8189 :language: yaml
8190 """
8191
8192 root = XML.SubElement(xml_parent, "hudson.plugins.tasks.TasksPublisher")
8193 root.set("plugin", "tasks")
8194
8195 if "files-to-scan" in data:
8196 XML.SubElement(root, "pattern").text = str(",".join(data["files-to-scan"]))
8197
8198 if "files-to-exclude" in data:
8199 XML.SubElement(root, "excludePattern").text = str(
8200 ",".join(data["files-to-exclude"])
8201 )
8202
8203 for prio in ["high", "normal", "low"]:
8204 if "tasks-tags-" + prio in data:
8205 XML.SubElement(root, prio).text = str(",".join(data["tasks-tags-" + prio]))
8206
8207 # on the UI, we can see compute-new-warnings but we need the opposite (XML)
8208 if "compute-new-warnings" in data and data["compute-new-warnings"]:
8209 XML.SubElement(root, "dontComputeNew").text = "false"
8210 else:
8211 XML.SubElement(root, "dontComputeNew").text = "true"
8212
8213 # Two parameters we cannot modify from the UI
8214 XML.SubElement(root, "pluginName").text = "[TASKS] "
8215 XML.SubElement(root, "doNotResolveRelativePaths").text = "false"
8216
8217 mappings = [
8218 ("ignore-case", "ignoreCase", False),
8219 ("regular-expression", "asRegexp", False),
8220 ("run-always", "canRunOnFailed", False),
8221 ("detect-module", "shouldDetectModules", False),
8222 ("health-thresholds-100", "healthy", ""),
8223 ("health-thresholds-0", "unHealthy", ""),
8224 ("health-priorities", "thresholdLimit", "low"),
8225 ("use-delta", "useDeltaValues", False),
8226 ("use-prev-build-as-ref", "usePreviousBuildAsReference", False),
8227 ("only-use-stable-as-ref", "useStableBuildAsReference", False),
8228 ("default-encoding", "defaultEncoding", ""),
8229 ]
8230 helpers.convert_mapping_to_xml(root, data, mappings, fail_required=True)
8231
8232 thrsh_xml = XML.SubElement(root, "thresholds")
8233 thrsh_xml.set("plugin", "analysis-core")
8234 thrsh_data = data.get("status-thresholds", {})
8235 thrsh_mappings = [
8236 ("unstable-total-all", "unstableTotalAll", ""),
8237 ("unstable-total-high", "unstableTotalHigh", ""),
8238 ("unstable-total-normal", "unstableTotalNormal", ""),
8239 ("unstable-total-low", "unstableTotalLow", ""),
8240 ("unstable-new-all", "unstableNewAll", ""),
8241 ("unstable-new-high", "unstableNewHigh", ""),
8242 ("unstable-new-normal", "unstableNewNormal", ""),
8243 ("unstable-new-low", "unstableNewLow", ""),
8244 ("failed-total-all", "failedTotalAll", ""),
8245 ("failed-total-high", "failedTotalHigh", ""),
8246 ("failed-total-normal", "failedTotalNormal", ""),
8247 ("failed-total-low", "failedTotalLow", ""),
8248 ("failed-new-all", "failedNewAll", ""),
8249 ("failed-new-high", "failedNewHigh", ""),
8250 ("failed-new-normal", "failedNewNormal", ""),
8251 ("failed-new-low", "failedNewLow", ""),
8252 ]
8253 helpers.convert_mapping_to_xml(
8254 thrsh_xml, thrsh_data, thrsh_mappings, fail_required=True
8255 )
8256
8257
8258 def packer(registry, xml_parent, data):
8259 """yaml: packer
8260 This plugin allows for a job to publish an image generated Packer
8261 Requires the Jenkins :jenkins-plugins:`Packer Plugin <packer>`.
8262
8263 :arg str name: Name of the packer installation (required)
8264 :arg str json-template: Path to a Packer JSON template file (default '')
8265 :arg str json-template-text: Text of Packer JSON template (default '')
8266 :arg str add-params: Specify which additional parameters
8267 to pass to packer (default '')
8268 :arg bool use-debug: adds -debug argument when packer executes
8269 (default false)
8270 :arg str change-dir: If set, the current directory will be changed
8271 to this before starting packer (default '')
8272 :arg str template-mode: Packer template option used (default global)
8273
8274 :template-mode values:
8275 * **global**
8276 * **file**
8277 * **text**
8278 :arg list file-entries: File entries for the packer
8279 configuration (default [])
8280 :arg str variable-name: Variable name for a file to used in the
8281 configuration JSON (default '')
8282 :arg str contents: File contents of the configuration JSON (default '')
8283
8284 Minimal Example:
8285
8286 .. literalinclude::
8287 /../../tests/publishers/fixtures/packer-minimal.yaml
8288 :language: yaml
8289
8290 Full Example:
8291
8292 .. literalinclude::
8293 /../../tests/publishers/fixtures/packer-full.yaml
8294 :language: yaml
8295 """
8296
8297 root = XML.SubElement(
8298 xml_parent, "biz.neustar.jenkins.plugins.packer.PackerPublisher"
8299 )
8300
8301 template_valid_types = ["global", "file", "text"]
8302 mapping = [
8303 ("name", "name", None),
8304 ("json-template", "jsonTemplate", ""),
8305 ("json-template-text", "jsonTemplateText", ""),
8306 ("add-params", "params", ""),
8307 ("use-debug", "useDebug", False),
8308 ("change-dir", "changeDir", ""),
8309 ("template-mode", "templateMode", "global", template_valid_types),
8310 ]
8311 helpers.convert_mapping_to_xml(root, data, mapping, fail_required=True)
8312
8313 format_dict = {
8314 "packer-file-entry": "biz.neustar.jenkins.plugins.packer.PackerFileEntry"
8315 }
8316 if "file-entries" in data:
8317 file_entries_tag = XML.SubElement(root, "fileEntries")
8318 for file_entries in data["file-entries"]:
8319 for file, params in file_entries.items():
8320 packer_file_entry_tag = XML.SubElement(
8321 file_entries_tag, format_dict.get("packer-file-entry")
8322 )
8323 XML.SubElement(packer_file_entry_tag, "varFileName").text = params.get(
8324 "variable-name", ""
8325 )
8326 XML.SubElement(packer_file_entry_tag, "contents").text = params.get(
8327 "contents", ""
8328 )
8329
8330
8331 def discord_notifier(registry, xml_parent, data):
8332 """yaml: discord-notifier
8333 This plugin allows for a job to publish results to discord
8334 Requires the Jenkins :jenkins-plugins:`discord-notifier`.
8335
8336 :arg str webhook-url: Discord webhook URL ( required )
8337
8338 Minimal Example:
8339
8340 .. literalinclude::
8341 /../../tests/publishers/fixtures/discord-notifier-minimal.yaml
8342 :language: yaml
8343
8344 Full Example:
8345
8346 .. literalinclude::
8347 /../../tests/publishers/fixtures/discord-notifier-full.yaml
8348 :language: yaml
8349
8350 """
8351
8352 boolean_options = {
8353 "send-on-state-change": "sendOnStateChange",
8354 "enable-url-linking": "enableUrlLinking",
8355 "enable-artifact-list": "enableArtifactList",
8356 "enable-footer-info": "enableFooterInfo",
8357 "show-changeset": "showChangeset",
8358 "send-log-file": "sendLogFile",
8359 "send-start-notification": "sendStartNotification",
8360 }
8361
8362 text_options = {
8363 "webhook-url": "webhookURL",
8364 "branch-name": "branchName",
8365 "status-title": "statusTitle",
8366 "thumbnail-url": "thumbnailURL",
8367 "notes": "notes",
8368 "custom-avatar-url": "customAvatarUrl",
8369 "custom-username": "customUsername",
8370 }
8371
8372 if data is None:
8373 data = dict()
8374
8375 notifier = XML.SubElement(
8376 xml_parent, "nz.co.jammehcow.jenkinsdiscord.WebhookPublisher "
8377 )
8378 notifier.set("plugin", "[email protected]")
8379
8380 for (opt, attr) in text_options.items():
8381 (XML.SubElement(notifier, attr).text) = data.get(opt)
8382
8383 for (opt, attr) in boolean_options.items():
8384 value = "true" if data.get(opt, False) else "false"
8385 (XML.SubElement(notifier, attr).text) = value
8386
8387
8388 class Publishers(jenkins_jobs.modules.base.Base):
8389 sequence = 70
8390
8391 component_type = "publisher"
8392 component_list_type = "publishers"
8393
8394 def gen_xml(self, xml_parent, data):
8395 if data.get("project-type", "freestyle") == "pipeline":
8396 logger.debug("Publishers skipped for Pipeline job")
8397 return
8398
8399 xml_publishers = XML.SubElement(xml_parent, "publishers")
8400
8401 component_list = data.get("publishers", [])
8402 self.dispatch_component_list("publisher", component_list, xml_publishers)