Debian Codegraph @

jenkins_jobs/modules/scm.py

raw
1 # Copyright 2012 Hewlett-Packard Development Company, L.P.
2 #
3 # Licensed under the Apache License, Version 2.0 (the "License");
4 # you may not use this file except in compliance with the License.
5 # You may obtain a copy of the License at
6 #
7 # http://www.apache.org/licenses/LICENSE-2.0
8 #
9 # Unless required by applicable law or agreed to in writing, software
10 # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11 # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12 # License for the specific language governing permissions and limitations
13 # under the License.
14
15
16 """
17 The SCM module allows you to specify the source code location for the
18 project. It adds the ``scm`` attribute to the :ref:`Job` definition,
19 which accepts any number of scm definitions. It is also possible to pass
20 ``[]`` to the ``scm`` attribute. This is useful when a set of configs has a
21 global default ``scm`` and you want to a particular job to override that
22 default with no SCM.
23
24 **Component**: scm
25 :Macro: scm
26 :Entry Point: jenkins_jobs.scm
27
28 The scm module allows referencing multiple repositories in a Jenkins job.
29 Note: Adding more than one scm definition requires the Jenkins
30 :jenkins-plugins:`Multiple SCMs plugin <multiple-scms>`.
31
32 Example of multiple repositories in a single job:
33 .. literalinclude:: /../../tests/macros/fixtures/scm/multi-scms001.yaml
34
35 Example of an empty ``scm``:
36 .. literalinclude:: /../../tests/scm/fixtures/empty.yaml
37 """
38
39 import logging
40 import xml.etree.ElementTree as XML
41
42 from jenkins_jobs.loc_loader import LocList
43 from jenkins_jobs.errors import InvalidAttributeError
44 from jenkins_jobs.errors import JenkinsJobsException
45 import jenkins_jobs.modules.base
46 import jenkins_jobs.modules.helpers as helpers
47
48
49 def p4(registry, xml_parent, data):
50 r"""yaml: p4
51 Specifies the Perforce (P4) repository for this job.
52
53 Requires the Jenkins :jenkins-plugins:`P4 Plugin <p4>`.
54 """
55 scm = XML.SubElement(
56 xml_parent,
57 "scm",
58 {"class": "org.jenkinsci.plugins.p4.PerforceScm", "plugin": "p4"},
59 )
60
61 XML.SubElement(scm, "credential").text = data.get("credential")
62
63 p4_construct_workspace(scm, data)
64
65 p4_construct_populate(scm, data)
66
67
68 def p4_construct_workspace(xml_parent, data):
69 workspace = None
70
71 workspace_mapping = [
72 ("workspace-charset", "charset", "none"),
73 ("workspace-pin-host", "pinHost", False),
74 ("workspace-name", "name", ""),
75 ("workspace-cleanup", "cleanup", None),
76 ]
77
78 if data.get("workspace-type") == "Static":
79 workspace = XML.SubElement(
80 xml_parent,
81 "workspace",
82 {"class": "org.jenkinsci.plugins.p4.workspace.StaticWorkspaceImpl"},
83 )
84 elif data.get("workspace-type") == "Manual":
85 workspace = XML.SubElement(
86 xml_parent,
87 "workspace",
88 {"class": "org.jenkinsci.plugins.p4.workspace.ManualWorkspaceImpl"},
89 )
90
91 spec = XML.SubElement(workspace, "spec")
92
93 spec_mapping = [
94 ("spec-allwrite", "allwrite", False),
95 ("spec-clobber", "clobber", False),
96 ("spec-compress", "compress", False),
97 ("spec-locked", "locked", False),
98 ("spec-modtime", "modtime", False),
99 ("spec-rmdir", "rmdir", False),
100 ("spec-line", "line", ""),
101 ("spec-view", "view", ""),
102 ("spec-type", "type", ""),
103 ("spec-backup", "backup", False),
104 ("spec-stream-name", "streamName", ""),
105 ]
106
107 helpers.convert_mapping_to_xml(spec, data, spec_mapping, fail_required=False)
108
109 if "view-mask" in data.keys():
110 filter_node = XML.SubElement(xml_parent, "filter")
111
112 view_mask = XML.SubElement(
113 filter_node, "org.jenkinsci.plugins.p4.filters.FilterViewMaskImpl"
114 )
115
116 view_mask_mapping = [("view-mask", "viewMask", None)]
117
118 helpers.convert_mapping_to_xml(
119 view_mask, data, view_mask_mapping, fail_required=False
120 )
121
122 helpers.convert_mapping_to_xml(
123 workspace, data, workspace_mapping, fail_required=False
124 )
125
126
127 def p4_construct_populate(xml_parent, data):
128 populate = None
129
130 populate_mapping = [
131 ("populate-have-list", "have", False),
132 ("populate-force-sync", "force", False),
133 ("populate-modtime", "modtime", False),
134 ("populate-quiet", "quiet", False),
135 ("populate-label", "pin", None),
136 ("populate-revert", "revert", None),
137 ("populate-replace", "replace", None),
138 ("populate-delete", "delete", None),
139 ("populate-tidy", "tidy", None),
140 ]
141
142 parallel_mapping = [
143 ("parallel-enabled", "enable", False),
144 ("parallel-threads", "threads", "4"),
145 ("parallel-minfiles", "minfiles", "1"),
146 ("parallel-minbytes", "minbytes", "1024"),
147 ]
148
149 if data.get("populate-type") == "SyncOnly":
150 populate = XML.SubElement(
151 xml_parent,
152 "populate",
153 {"class": "org.jenkinsci.plugins.p4.populate.SyncOnlyImpl"},
154 )
155 elif data.get("populate-type") == "AutoClean":
156 populate = XML.SubElement(
157 xml_parent,
158 "populate",
159 {"class": "org.jenkinsci.plugins.p4.populate.AutoCleanImpl"},
160 )
161
162 helpers.convert_mapping_to_xml(
163 populate, data, populate_mapping, fail_required=False
164 )
165
166 parallel = XML.SubElement(populate, "parallel")
167
168 helpers.convert_mapping_to_xml(
169 parallel, data, parallel_mapping, fail_required=False
170 )
171
172
173 def git(registry, xml_parent, data):
174 r"""yaml: git
175 Specifies the git SCM repository for this job.
176
177 Requires the Jenkins :jenkins-plugins:`Git Plugin <git>`.
178
179 :arg str url: URL of the git repository
180 :arg str credentials-id: ID of credential to use to connect, which is the
181 last field (a 32-digit hexadecimal code) of the path of URL visible
182 after you clicked the credential under Jenkins Global credentials.
183 (optional)
184 :arg str refspec: refspec to fetch (default
185 '+refs/heads/\*:refs/remotes/remoteName/\*')
186 :arg str name: name to fetch (default 'origin')
187 :arg list(str) remotes: list of remotes to set up (optional, only needed if
188 multiple remotes need to be set up)
189
190 :Remote:
191 * **url** (`string`) - url of remote repo
192 * **refspec** (`string`) - refspec to fetch (optional)
193 * **credentials-id** - ID of credential to use to connect, which
194 is the last field of the path of URL (a 32-digit hexadecimal
195 code) visible after you clicked credential under Jenkins Global
196 credentials. (optional)
197 :arg list(str) branches: list of branch specifiers to build (default '**')
198 :arg bool skip-tag: Skip tagging (default true)
199
200 .. deprecated:: 2.0.0. Please use per-build-tag extension, which has
201 the inverse meaning.
202
203 :arg bool clean: Clean after checkout (default false)
204
205 .. deprecated:: 1.1.1. Please use clean extension format.
206
207 :arg bool fastpoll: Use fast remote polling (default false)
208 :arg bool disable-submodules: Disable submodules (default false)
209
210 .. deprecated:: 1.1.1. Please use submodule extension.
211
212 :arg bool recursive-submodules: Recursively update submodules (default
213 false)
214
215 .. deprecated:: 1.1.1. Please use submodule extension.
216
217 :arg str git-tool: The name of the Git installation to use (default
218 'Default')
219 :arg str reference-repo: Path of the reference repo to use during clone
220 (optional)
221 :arg str browser: what repository browser to use.
222
223 :browsers supported:
224 * **auto** - (default)
225 * **assemblaweb** - https://get.assembla.com/
226 * **bitbucketweb** - https://bitbucket.org/
227 * **cgit** - https://git.zx2c4.com/cgit/about/
228 * **fisheye** - https://www.atlassian.com/software/fisheye
229 * **gitblit** - http://gitblit.com/
230 * **githubweb** - https://github.com/
231 * **gitiles** - https://code.google.com/archive/p/gitiles/
232 * **gitlab** - https://about.gitlab.com/
233 * **gitlist** - https://gitlist.org/
234 * **gitoriousweb** - https://gitorious.org/
235 * **gitweb** - https://git-scm.com/docs/gitweb
236 * **kiln** - https://ignitetech.com/softwarelibrary/fogbugz
237 * **microsoft\-tfs\-2013** - |tfs_2013|
238 * **phabricator** - https://www.phacility.com/
239 * **redmineweb** - https://www.redmine.org/
240 * **rhodecode** - https://rhodecode.com/
241 * **stash** - https://www.atlassian.com/software/bitbucket/enterprise/data-center
242 * **viewgit**
243 :arg str browser-url: url for the repository browser (required if browser
244 is not 'auto', no default)
245 :arg str browser-version: version of the repository browser (GitLab only,
246 default '0.0')
247 :arg str project-name: project name in Gitblit and ViewGit repobrowser
248 (optional)
249 :arg str repo-name: repository name in phabricator repobrowser (optional)
250 :arg str git-config-name: Configure name for Git clone (optional)
251 :arg str git-config-email: Configure email for Git clone (optional)
252
253 :extensions:
254
255 * **basedir** (`string`) - Location relative to the workspace root to
256 clone to (default workspace)
257 * **changelog-against** (`dict`)
258 * **remote** (`string`) - name of repo that contains branch to
259 create changelog against (default 'origin')
260 * **branch** (`string`) - name of the branch to create changelog
261 against (default 'master')
262 * **choosing-strategy**: (`string`) - Jenkins class for selecting what
263 to build. Can be one of `default`,`inverse`, or `gerrit`
264 (default 'default')
265 * **clean** (`dict`)
266 * **after** (`dict`) - Clean the workspace after checkout
267 * **remove-stale-nested-repos** (`bool`) - Deletes untracked
268 submodules and any other subdirectories which contain .git directories
269 (default false)
270 * **before** (`dict`) - Clean the workspace before checkout
271 * **remove-stale-nested-repos** (`bool`) - Deletes untracked
272 submodules and any other subdirectories which contain .git directories
273 (default false)
274 * **committer** (`dict`)
275 * **name** (`str`) - Name to use as author of new commits
276 * **email** (`str`) - E-mail address to use for new commits
277 * **excluded-users**: (`list(string)`) - list of users to ignore
278 revisions from when polling for changes.
279 (if polling is enabled, optional)
280 * **included-regions**: (`list(string)`) - list of file/folders to
281 include (optional)
282 * **excluded-regions**: (`list(string)`) - list of file/folders to
283 exclude (optional)
284 * **ignore-commits-with-messages** (`list(str)`) - Revisions committed
285 with messages matching these patterns will be ignored. (optional)
286 * **ignore-notify**: (`bool`) - Ignore notifyCommit URL accesses
287 (default false)
288 * **force-polling-using-workspace** (`bool`) - Force polling using
289 workspace (default false)
290 * **local-branch** (`string`) - Checkout/merge to local branch
291 (optional)
292 * **merge** (`dict`)
293 * **remote** (`string`) - name of repo that contains branch to
294 merge to (default 'origin')
295 * **branch** (`string`) - name of the branch to merge to
296 * **strategy** (`string`) - merge strategy. Can be one of
297 'default', 'resolve', 'recursive', 'octopus', 'ours',
298 'subtree'. (default 'default')
299 * **fast-forward-mode** (`string`) - merge fast-forward mode.
300 Can be one of 'FF', 'FF_ONLY' or 'NO_FF'. (default 'FF')
301 * **per-build-tag** (`bool`) - Create a tag in the workspace for every
302 build. (default is inverse of skip-tag if set, otherwise false)
303 * **prune** (`bool`) - Prune remote branches (default false)
304 * **scm-name** (`string`) - The unique scm name for this Git SCM
305 (optional)
306 * **shallow-clone** (`bool`) - Perform shallow clone (default false)
307 * **depth** (`int`) - Set shallow clone depth (default 1)
308 * **do-not-fetch-tags** (`bool`) - Perform a clone without tags
309 (default false)
310 * **honor-refspec** (`bool`) - Perform initial clone using the refspec
311 defined for the repository (default false)
312 * **skip-notifications** (`bool`) - Skip build status notifications
313 (default false). Requires the Jenkins
314 :jenkins-plugins:`Skip Notifications Trait Plugin <skip-notifications-trait>`.
315 * **sparse-checkout** (`dict`)
316 * **paths** (`list`) - List of paths to sparse checkout. (optional)
317 * **submodule** (`dict`)
318 * **disable** (`bool`) - By disabling support for submodules you
319 can still keep using basic git plugin functionality and just have
320 Jenkins to ignore submodules completely as if they didn't exist.
321 * **recursive** (`bool`) - Retrieve all submodules recursively
322 (uses '--recursive' option which requires git>=1.6.5)
323 * **tracking** (`bool`) - Retrieve the tip of the configured
324 branch in .gitmodules (Uses '\-\-remote' option which requires
325 git>=1.8.2)
326 * **parent-credentials** (`bool`) - Use credentials from default
327 remote of parent repository (default false).
328 * **reference-repo** (`str`) - Path of the reference repo to use
329 during clone (optional)
330 * **timeout** (`int`) - Specify a timeout (in minutes) for
331 submodules operations (default 10).
332 * **threads** (`int`) - Number of parallel processes to be used when
333 updating submodules. Default is to use a single thread for submodule updates.
334 * **timeout** (`str`) - Timeout for git commands in minutes (optional)
335 * **use-author** (`bool`): Use author rather than committer in Jenkin's
336 build changeset (default false)
337 * **wipe-workspace** (`bool`) - Wipe out workspace before build
338 (default true)
339 * **lfs-pull** (`bool`) - Call git lfs pull after checkout
340 (default false)
341
342
343 Example:
344
345 .. literalinclude:: /../../tests/scm/fixtures/git001.yaml
346
347 .. |tfs_2013| replace::
348 https://azure.microsoft.com/en-us/products/devops/server/
349
350 """
351 logger = logging.getLogger("%s:git" % __name__)
352
353 # XXX somebody should write the docs for those with option name =
354 # None so we have a sensible name/key for it.
355 mapping = [
356 # option, xml name, default value (text), attributes (hard coded)
357 ("disable-submodules", "disableSubmodules", False),
358 ("recursive-submodules", "recursiveSubmodules", False),
359 (None, "doGenerateSubmoduleConfigurations", False),
360 # XXX is this the same as force-polling-using-workspace?
361 ("fastpoll", "remotePoll", False),
362 # XXX does this option still exist?
363 ("git-tool", "gitTool", "Default"),
364 (None, "submoduleCfg", "", {"class": "list"}),
365 ("reference-repo", "reference", ""),
366 ("git-config-name", "gitConfigName", ""),
367 ("git-config-email", "gitConfigEmail", ""),
368 ]
369
370 scm = XML.SubElement(xml_parent, "scm", {"class": "hudson.plugins.git.GitSCM"})
371 XML.SubElement(scm, "configVersion").text = "2"
372 user = XML.SubElement(scm, "userRemoteConfigs")
373 if "remotes" not in data:
374 data["remotes"] = [{data.get("name", "origin"): data.copy()}]
375 for remoteData in data["remotes"]:
376 huser = XML.SubElement(user, "hudson.plugins.git.UserRemoteConfig")
377 remoteName = next(iter(remoteData.keys()))
378 XML.SubElement(huser, "name").text = remoteName
379 remoteParams = next(iter(remoteData.values()))
380 if "refspec" in remoteParams:
381 refspec = remoteParams["refspec"]
382 else:
383 refspec = "+refs/heads/*:refs/remotes/" + remoteName + "/*"
384 XML.SubElement(huser, "refspec").text = refspec
385 if "url" in remoteParams:
386 remoteURL = remoteParams["url"]
387 else:
388 raise JenkinsJobsException(
389 'Must specify a url for git remote "' + remoteName + '"'
390 )
391 XML.SubElement(huser, "url").text = remoteURL
392 if "credentials-id" in remoteParams:
393 credentialsId = remoteParams["credentials-id"]
394 XML.SubElement(huser, "credentialsId").text = credentialsId
395 xml_branches = XML.SubElement(scm, "branches")
396 branches = data.get("branches", ["**"])
397 for branch in branches:
398 bspec = XML.SubElement(xml_branches, "hudson.plugins.git.BranchSpec")
399 XML.SubElement(bspec, "name").text = branch
400 for elem in mapping:
401 (optname, xmlname, val) = elem[:3]
402
403 # Throw warning for deprecated settings and skip if the 'submodule' key
404 # is available.
405 submodule_cfgs = ["disable-submodules", "recursive-submodules"]
406 if optname in submodule_cfgs:
407 if optname in data:
408 logger.warning(
409 "'{0}' is deprecated, please convert to use the "
410 "'submodule' section instead as support for this "
411 "top level option will be removed in a future "
412 "release.".format(optname)
413 )
414 if "submodule" in data:
415 continue
416
417 attrs = {}
418 if len(elem) >= 4:
419 attrs = elem[3]
420 xe = XML.SubElement(scm, xmlname, attrs)
421 if optname and optname in data:
422 val = data[optname]
423 if type(val) is bool:
424 xe.text = str(val).lower()
425 else:
426 xe.text = val
427
428 exts = XML.SubElement(scm, "extensions")
429
430 # handle all supported git extensions
431 git_extensions(exts, data)
432
433 browser = data.get("browser", "auto")
434 browserdict = {
435 "auto": "auto",
436 "assemblaweb": "AssemblaWeb",
437 "bitbucketweb": "BitbucketWeb",
438 "cgit": "CGit",
439 "fisheye": "FisheyeGitRepositoryBrowser",
440 "gitblit": "GitBlitRepositoryBrowser",
441 "githubweb": "GithubWeb",
442 "gitiles": "Gitiles",
443 "gitlab": "GitLab",
444 "gitlist": "GitList",
445 "gitoriousweb": "GitoriousWeb",
446 "gitweb": "GitWeb",
447 "kiln": "KilnGit",
448 "microsoft-tfs-2013": "TFS2013GitRepositoryBrowser",
449 "phabricator": "Phabricator",
450 "redmineweb": "RedmineWeb",
451 "rhodecode": "RhodeCode",
452 "stash": "Stash",
453 "viewgit": "ViewGitWeb",
454 }
455 if browser not in browserdict:
456 valid = sorted(browserdict.keys())
457 raise JenkinsJobsException(
458 "Browser entered is not valid must be one "
459 "of: %s or %s." % (", ".join(valid[:-1]), valid[-1])
460 )
461 if browser != "auto":
462 bc = XML.SubElement(
463 scm,
464 "browser",
465 {"class": "hudson.plugins.git.browser." + browserdict[browser]},
466 )
467 XML.SubElement(bc, "url").text = data["browser-url"]
468 if browser in ["gitblit", "viewgit"]:
469 XML.SubElement(bc, "projectName").text = str(data.get("project-name", ""))
470 if browser == "gitlab":
471 XML.SubElement(bc, "version").text = str(data.get("browser-version", "0.0"))
472 if browser == "phabricator":
473 XML.SubElement(bc, "repo").text = str(data.get("repo-name", ""))
474
475
476 def git_extensions(xml_parent, data):
477 logger = logging.getLogger("%s:git_extensions" % __name__)
478
479 trait = xml_parent.tag == "traits"
480
481 # list of availavble traits here: https://bit.ly/2CNEtqS
482 trait_prefix = "jenkins.plugins.git.traits."
483 impl_prefix = "hudson.plugins.git.extensions.impl."
484
485 choosing_strategies = {
486 "default": "hudson.plugins.git.util.DefaultBuildChooser",
487 "gerrit": (
488 "com.sonyericsson.hudson.plugins."
489 "gerrit.trigger.hudsontrigger.GerritTriggerBuildChooser"
490 ),
491 "inverse": "hudson.plugins.git.util.InverseBuildChooser",
492 }
493
494 if not trait and "basedir" in data:
495 ext = XML.SubElement(xml_parent, impl_prefix + "RelativeTargetDirectory")
496 XML.SubElement(ext, "relativeTargetDir").text = data["basedir"]
497 if not trait and "changelog-against" in data:
498 ext_name = impl_prefix + "ChangelogToBranch"
499 ext = XML.SubElement(xml_parent, ext_name)
500 opts = XML.SubElement(ext, "options")
501 change_remote = data["changelog-against"].get("remote", "origin")
502 change_branch = data["changelog-against"].get("branch", "master")
503 XML.SubElement(opts, "compareRemote").text = change_remote
504 XML.SubElement(opts, "compareTarget").text = change_branch
505 if not trait and "choosing-strategy" in data:
506 try:
507 choosing_strategy = choosing_strategies[data.get("choosing-strategy")]
508 except KeyError:
509 raise ValueError(
510 "Invalid choosing-strategy %r" % data.get("choosing-strategy")
511 )
512 ext = XML.SubElement(xml_parent, impl_prefix + "BuildChooserSetting")
513 XML.SubElement(ext, "buildChooser", {"class": choosing_strategy})
514 if "clean" in data:
515 # Keep support for old format 'clean' configuration by checking
516 # if 'clean' is boolean. Else we're using the new extensions style.
517 if isinstance(data["clean"], bool):
518 clean_after = data["clean"]
519 clean_before = False
520 logger.warning(
521 "'clean: bool' configuration format is deprecated, "
522 "please use the extension style format to configure "
523 "this option."
524 )
525 else:
526 clean_after = data["clean"].get("after", False)
527 clean_before = data["clean"].get("before", False)
528 if clean_after is not False:
529 if isinstance(clean_after, bool):
530 clean_after_opts = {}
531 logger.warning(
532 "'clean: after: bool' configuration format is deprecated, "
533 "after should be an empty dict or filled with accepted "
534 "options."
535 )
536 else:
537 clean_after_opts = clean_after
538
539 ext_name = impl_prefix + "CleanCheckout"
540 if trait:
541 trait_name = "CleanAfterCheckoutTrait"
542 tr = XML.SubElement(xml_parent, trait_prefix + trait_name)
543 ext = XML.SubElement(tr, "extension", {"class": ext_name})
544 else:
545 ext = XML.SubElement(xml_parent, ext_name)
546 if "remove-stale-nested-repos" in clean_after_opts:
547 elm = XML.SubElement(ext, "deleteUntrackedNestedRepositories")
548 elm.text = "true"
549 if clean_before is not False:
550 if isinstance(clean_before, bool):
551 clean_before_opts = {}
552 logger.warning(
553 "'clean: before: bool' configuration format is deprecated, "
554 "before should be an empty dict or filled with accepted "
555 "options."
556 )
557 else:
558 clean_before_opts = clean_before
559
560 ext_name = impl_prefix + "CleanBeforeCheckout"
561 if trait:
562 trait_name = "CleanBeforeCheckoutTrait"
563 tr = XML.SubElement(xml_parent, trait_prefix + trait_name)
564 ext = XML.SubElement(tr, "extension", {"class": ext_name})
565 else:
566 ext = XML.SubElement(xml_parent, ext_name)
567 if "remove-stale-nested-repos" in clean_before_opts:
568 elm = XML.SubElement(ext, "deleteUntrackedNestedRepositories")
569 elm.text = "true"
570 committer = data.get("committer", {})
571 if committer:
572 ext_name = impl_prefix + "UserIdentity"
573 if trait:
574 trait_name = "com.cloudbees.jenkins.plugins.bitbucket.notifications.SkipNotificationsTrait"
575 trait_name = "UserIdentityTrait"
576 tr = XML.SubElement(xml_parent, trait_prefix + trait_name)
577 ext = XML.SubElement(tr, "extension", {"class": ext_name})
578 else:
579 ext = XML.SubElement(xml_parent, ext_name)
580 name = committer.get("name")
581 if name:
582 XML.SubElement(ext, "name").text = name
583 email = committer.get("email")
584 if email:
585 XML.SubElement(ext, "email").text = email
586 if not trait and "excluded-users" in data:
587 excluded_users = "\n".join(data["excluded-users"])
588 ext = XML.SubElement(xml_parent, impl_prefix + "UserExclusion")
589 XML.SubElement(ext, "excludedUsers").text = excluded_users
590 if not trait and "included-regions" in data or "excluded-regions" in data:
591 ext = XML.SubElement(
592 xml_parent, "hudson.plugins.git.extensions.impl." "PathRestriction"
593 )
594 if "included-regions" in data:
595 include_string = "\n".join(data["included-regions"])
596 XML.SubElement(ext, "includedRegions").text = include_string
597 if "excluded-regions" in data:
598 exclude_string = "\n".join(data["excluded-regions"])
599 XML.SubElement(ext, "excludedRegions").text = exclude_string
600 if not trait and "ignore-commits-with-messages" in data:
601 for msg in data["ignore-commits-with-messages"]:
602 ext_name = impl_prefix + "MessageExclusion"
603 ext = XML.SubElement(xml_parent, ext_name)
604 XML.SubElement(ext, "excludedMessage").text = msg
605 if not trait and "local-branch" in data:
606 ext = XML.SubElement(xml_parent, impl_prefix + "LocalBranch")
607 XML.SubElement(ext, "localBranch").text = str(data["local-branch"])
608 if not trait and "merge" in data:
609 merge = data["merge"]
610 merge_strategies = [
611 "default",
612 "resolve",
613 "recursive",
614 "octopus",
615 "ours",
616 "subtree",
617 ]
618 fast_forward_modes = ["FF", "FF_ONLY", "NO_FF"]
619 name = merge.get("remote", "origin")
620 branch = merge["branch"]
621 ext = XML.SubElement(xml_parent, impl_prefix + "PreBuildMerge")
622 merge_opts = XML.SubElement(ext, "options")
623 XML.SubElement(merge_opts, "mergeRemote").text = name
624 XML.SubElement(merge_opts, "mergeTarget").text = branch
625 strategy = merge.get("strategy", "default")
626 if strategy not in merge_strategies:
627 raise InvalidAttributeError("strategy", strategy, merge_strategies)
628 XML.SubElement(merge_opts, "mergeStrategy").text = strategy
629 fast_forward_mode = merge.get("fast-forward-mode", "FF")
630 if fast_forward_mode not in fast_forward_modes:
631 raise InvalidAttributeError(
632 "fast-forward-mode", fast_forward_mode, fast_forward_modes
633 )
634 XML.SubElement(merge_opts, "fastForwardMode").text = fast_forward_mode
635 if not trait and "scm-name" in data:
636 ext = XML.SubElement(xml_parent, impl_prefix + "ScmName")
637 XML.SubElement(ext, "name").text = str(data["scm-name"])
638
639 clone_options = (
640 "shallow-clone",
641 "timeout",
642 "do-not-fetch-tags",
643 "honor-refspec",
644 "reference-repo",
645 )
646 if any(key in data for key in clone_options):
647 ext_name = impl_prefix + "CloneOption"
648
649 if trait:
650 tr = XML.SubElement(xml_parent, trait_prefix + "CloneOptionTrait")
651 ext = XML.SubElement(tr, "extension", {"class": ext_name})
652 else:
653 ext = XML.SubElement(xml_parent, ext_name)
654
655 clone_mapping = [("shallow-clone", "shallow", False), ("depth", "depth", 1)]
656 helpers.convert_mapping_to_xml(ext, data, clone_mapping, fail_required=True)
657 if "do-not-fetch-tags" in data:
658 XML.SubElement(ext, "noTags").text = str(
659 data.get("do-not-fetch-tags", False)
660 ).lower()
661 if "timeout" in data:
662 XML.SubElement(ext, "timeout").text = str(data["timeout"])
663 if "honor-refspec" in data:
664 XML.SubElement(ext, "honorRefspec").text = str(
665 data.get("honor-refspec", False)
666 ).lower()
667 if "reference-repo" in data:
668 XML.SubElement(ext, "reference").text = str(data["reference-repo"])
669 skip_notifications = data.get("skip-notifications", False)
670 if trait and skip_notifications:
671 trait_name = "com.cloudbees.jenkins.plugins.bitbucket.notifications.SkipNotificationsTrait"
672 XML.SubElement(xml_parent, trait_name)
673 if "sparse-checkout" in data:
674 ext_name = impl_prefix + "SparseCheckoutPaths"
675 if trait:
676 trait_name = "SparseCheckoutPathsTrait"
677 tr = XML.SubElement(xml_parent, trait_prefix + trait_name)
678 ext = XML.SubElement(tr, "extension", {"class": ext_name})
679 else:
680 ext = XML.SubElement(xml_parent, ext_name)
681 sparse_co = XML.SubElement(ext, "sparseCheckoutPaths")
682 sparse_paths = data["sparse-checkout"].get("paths")
683 if sparse_paths is not None:
684 path_tagname = impl_prefix + "SparseCheckoutPath"
685 for path in sparse_paths:
686 path_tag = XML.SubElement(sparse_co, path_tagname)
687 XML.SubElement(path_tag, "path").text = path
688 if "submodule" in data:
689 ext_name = impl_prefix + "SubmoduleOption"
690 if trait:
691 trait_name = "SubmoduleOptionTrait"
692 tr = XML.SubElement(xml_parent, trait_prefix + trait_name)
693 ext = XML.SubElement(tr, "extension", {"class": ext_name})
694 else:
695 ext = XML.SubElement(xml_parent, ext_name)
696
697 XML.SubElement(ext, "disableSubmodules").text = str(
698 data["submodule"].get("disable", False)
699 ).lower()
700 XML.SubElement(ext, "recursiveSubmodules").text = str(
701 data["submodule"].get("recursive", False)
702 ).lower()
703 XML.SubElement(ext, "trackingSubmodules").text = str(
704 data["submodule"].get("tracking", False)
705 ).lower()
706 XML.SubElement(ext, "parentCredentials").text = str(
707 data["submodule"].get("parent-credentials", False)
708 ).lower()
709 XML.SubElement(ext, "reference").text = str(
710 data["submodule"].get("reference-repo", "")
711 )
712 XML.SubElement(ext, "timeout").text = str(data["submodule"].get("timeout", 10))
713 XML.SubElement(ext, "threads").text = str(data["submodule"].get("threads", 1))
714 if "timeout" in data:
715 ext_name = impl_prefix + "CheckoutOption"
716 if trait:
717 trait_name = "CheckoutOptionTrait"
718 tr = XML.SubElement(xml_parent, trait_prefix + trait_name)
719 ext = XML.SubElement(tr, "extension", {"class": ext_name})
720 else:
721 ext = XML.SubElement(xml_parent, ext_name)
722 XML.SubElement(ext, "timeout").text = str(data["timeout"])
723
724 polling_using_workspace = str(
725 data.get("force-polling-using-workspace", False)
726 ).lower()
727 if not trait and polling_using_workspace == "true":
728 ext_name = impl_prefix + "DisableRemotePoll"
729 ext = XML.SubElement(xml_parent, ext_name)
730 if not trait and "per-build-tag" in data or "skip-tag" in data:
731 # We want to support both skip-tag (the old option) and per-build-tag
732 # (the new option), with the new one overriding the old one.
733 # Unfortunately they have inverse meanings, so we have to be careful.
734 # The default value of per-build-tag is False if skip-tag is not set,
735 # so we set the default value of skip-tag to True.
736 per_build_tag_default = False
737 if str(data.get("skip-tag", True)).lower() == "false":
738 per_build_tag_default = True
739 if str(data.get("per-build-tag", per_build_tag_default)).lower() == "true":
740 XML.SubElement(xml_parent, impl_prefix + "PerBuildTag")
741 prune = str(data.get("prune", False)).lower()
742 if prune == "true":
743 ext_name = impl_prefix + "PruneStaleBranch"
744 if trait:
745 trait_name = "PruneStaleBranchTrait"
746 tr = XML.SubElement(xml_parent, trait_prefix + trait_name)
747 ext = XML.SubElement(tr, "extension", {"class": ext_name})
748 else:
749 ext = XML.SubElement(xml_parent, ext_name)
750 ignore_notify_commits = str(data.get("ignore-notify", False)).lower()
751 if not trait and ignore_notify_commits == "true":
752 XML.SubElement(xml_parent, impl_prefix + "IgnoreNotifyCommit")
753 # By default we wipe the workspace
754 wipe_workspace = str(data.get("wipe-workspace", True)).lower()
755 if wipe_workspace == "true":
756 ext_name = impl_prefix + "WipeWorkspace"
757 if trait:
758 trait_name = "WipeWorkspaceTrait"
759 tr = XML.SubElement(xml_parent, trait_prefix + trait_name)
760 ext = XML.SubElement(tr, "extension", {"class": ext_name})
761 else:
762 ext = XML.SubElement(xml_parent, ext_name)
763
764 use_author = str(data.get("use-author", False)).lower()
765 if use_author == "true":
766 ext_name = impl_prefix + "AuthorInChangelog"
767 if trait:
768 trait_name = "AuthorInChangelogTrait"
769 tr = XML.SubElement(xml_parent, trait_prefix + trait_name)
770 ext = XML.SubElement(tr, "extension", {"class": ext_name})
771 else:
772 ext = XML.SubElement(xml_parent, ext_name)
773
774 lfs_pull = str(data.get("lfs-pull", False)).lower()
775 if lfs_pull == "true":
776 ext_name = impl_prefix + "GitLFSPull"
777 if trait:
778 trait_name = "GitLFSPullTrait"
779 tr = XML.SubElement(xml_parent, trait_prefix + trait_name)
780 XML.SubElement(tr, "extension", {"class": ext_name})
781 else:
782 XML.SubElement(xml_parent, ext_name)
783
784
785 def cvs(registry, xml_parent, data):
786 """yaml: cvs
787 Specifies the CVS SCM repository for this job.
788
789 Requires the Jenkins :jenkins-plugins:`CVS Plugin <cvs>`.
790
791 :arg list repos: List of CVS repositories. (required)
792
793 :Repos:
794 * **root** (`str`) -- The CVS connection string Jenkins uses to
795 connect to the server. The format is :protocol:user@host:path
796 (required)
797 * **locations** (`list`) -- List of locations. (required)
798
799 :Locations:
800 * **type** (`str`) -- Type of location.
801
802 :supported values:
803 * **HEAD** - (default)
804 * **BRANCH**
805 * **TAG**
806 * **name** (`str`) -- Name of location. Only valid in case
807 of 'BRANCH' or 'TAG' location type. (default '')
808 * **use-head** (`bool`) -- Use Head if not found. Only
809 valid in case of 'BRANCH' or 'TAG' location type.
810 (default false)
811 * **modules** (`list`) -- List of modules. (required)
812
813 :Modules:
814 * **remote** -- The name of the module in the
815 repository at CVSROOT. (required)
816 * **local-name** -- The name to be applied to
817 this module in the local workspace. If blank,
818 the remote module name will be used.
819 (default '')
820 * **excluded-regions** (`list str`) -- Patterns for excluding
821 regions. (optional)
822 * **compression-level** (`int`) -- Compression level. Must be a
823 number between -1 and 9 inclusive. Choose -1 for System Default.
824 (default -1)
825 :arg bool use-update: If true, Jenkins will use 'cvs update' whenever
826 possible for builds. This makes a build faster. But this also causes the
827 artifacts from the previous build to remain in the file system when a
828 new build starts, making it not a true clean build. (default true)
829 :arg bool prune-empty: Remove empty directories after checkout using the
830 CVS '-P' option. (default true)
831 :arg bool skip-changelog: Prevent the changelog being generated after
832 checkout has completed. (default false)
833 :arg bool show-all-output: Instructs CVS to show all logging output. CVS
834 normally runs in quiet mode but this option disables that.
835 (default false)
836 :arg bool clean-checkout: Perform clean checkout on failed update.
837 (default false)
838 :arg bool clean-copy: Force clean copy for locally modified files.
839 (default false)
840
841 Example
842
843 .. literalinclude:: /../../tests/scm/fixtures/cvs001.yaml
844 :language: yaml
845 .. literalinclude:: /../../tests/scm/fixtures/cvs002.yaml
846 :language: yaml
847 """
848 prefix = "hudson.scm."
849 valid_loc_types = {"HEAD": "Head", "TAG": "Tag", "BRANCH": "Branch"}
850
851 cvs = XML.SubElement(xml_parent, "scm", {"class": prefix + "CVSSCM"})
852 repos = data.get("repos")
853 repos_tag = XML.SubElement(cvs, "repositories")
854 for repo in repos:
855 repo_tag = XML.SubElement(repos_tag, prefix + "CvsRepository")
856 compression_level = repo.get("compression-level", "-1")
857 repo_mapping = [
858 ("root", "cvsRoot", None),
859 ("", "compressionLevel", int(compression_level), range(-1, 10)),
860 ]
861 helpers.convert_mapping_to_xml(repo_tag, repo, repo_mapping, fail_required=True)
862
863 items_tag = XML.SubElement(repo_tag, "repositoryItems")
864 locations = repo.get("locations")
865 for location in locations:
866 item_tag = XML.SubElement(items_tag, prefix + "CvsRepositoryItem")
867 loc_type = location.get("type", "HEAD")
868 if loc_type not in valid_loc_types:
869 raise InvalidAttributeError("type", loc_type, valid_loc_types)
870 loc_class = ("{0}CvsRepositoryLocation${1}Repository" "Location").format(
871 prefix, valid_loc_types[loc_type]
872 )
873 loc_tag = XML.SubElement(item_tag, "location", {"class": loc_class})
874 mapping = [("type", "locationType", "HEAD")]
875 helpers.convert_mapping_to_xml(
876 loc_tag, location, mapping, fail_required=True
877 )
878
879 if loc_type != "HEAD":
880 mapping = [
881 ("name", "locationName", ""),
882 ("use-head", "useHeadIfNotFound", False),
883 ]
884 helpers.convert_mapping_to_xml(
885 loc_tag, location, mapping, fail_required=True
886 )
887
888 modules = location.get("modules")
889 modules_tag = XML.SubElement(item_tag, "modules")
890 for module in modules:
891 module_tag = XML.SubElement(modules_tag, prefix + "CvsModule")
892 mapping = [
893 ("remote", "remoteName", None),
894 ("local-name", "localName", ""),
895 ]
896 helpers.convert_mapping_to_xml(
897 module_tag, module, mapping, fail_required=True
898 )
899
900 excluded = repo.get("excluded-regions", [])
901 excluded_tag = XML.SubElement(repo_tag, "excludedRegions")
902 for pattern in excluded:
903 pattern_tag = XML.SubElement(excluded_tag, prefix + "ExcludedRegion")
904 XML.SubElement(pattern_tag, "pattern").text = pattern
905
906 mappings = [
907 ("use-update", "canUseUpdate", True),
908 ("prune-empty", "pruneEmptyDirectories", True),
909 ("skip-changelog", "skipChangeLog", False),
910 ("show-all-output", "disableCvsQuiet", False),
911 ("clean-checkout", "cleanOnFailedUpdate", False),
912 ("clean-copy", "forceCleanCopy", False),
913 ]
914 helpers.convert_mapping_to_xml(cvs, data, mappings, fail_required=True)
915
916
917 def repo(registry, xml_parent, data):
918 """yaml: repo
919 Specifies the repo SCM repository for this job.
920
921 Requires the Jenkins :jenkins-plugins:`Repo Plugin <repo>`.
922
923 :arg str manifest-url: URL of the repo manifest (required)
924 :arg str manifest-branch: The branch of the manifest to use (optional)
925 :arg str manifest-file: Initial manifest file to use when initialising
926 (optional)
927 :arg str manifest-group: Only retrieve those projects in the manifest
928 tagged with the provided group name (optional)
929 :arg list(str) ignore-projects: a list of projects in which changes would
930 not be considered to trigger a build when pooling (optional)
931 :arg str destination-dir: Location relative to the workspace root to clone
932 under (optional)
933 :arg str repo-url: custom url to retrieve the repo application (optional)
934 :arg str mirror-dir: Path to mirror directory to reference when
935 initialising (optional)
936 :arg int jobs: Number of projects to fetch simultaneously (default 0)
937 :arg int depth: Specify the depth in history to sync from the source. The
938 default is to sync all of the history. Use 1 to just sync the most
939 recent commit (default 0)
940 :arg bool current-branch: Fetch only the current branch from the server
941 (default true)
942 :arg bool reset-first: Remove any commits that are not on the repositories
943 by running the following command before anything else (default false):
944 ``repo forall -c "git reset --hard"``
945 :arg bool clean-first: Remove any files that are not tracked in the repositories
946 by running the following command before anything else (default false):
947 ``repo forall -c "git clean -fdx"``
948 :arg bool quiet: Make repo more quiet
949 (default true)
950 :arg bool force-sync: Continue sync even if a project fails to sync
951 (default false)
952 :arg bool no-tags: Don't fetch tags (default false)
953 :arg bool trace: Trace git command execution into the build logs. (default
954 false)
955 :arg bool show-all-changes: When this is checked --first-parent is no
956 longer passed to git log when determining changesets (default false)
957 :arg str local-manifest: Contents of .repo/local_manifest.xml, written
958 prior to calling sync (optional)
959
960 Example:
961
962 .. literalinclude:: /../../tests/scm/fixtures/repo001.yaml
963 """
964
965 scm = XML.SubElement(xml_parent, "scm", {"class": "hudson.plugins.repo.RepoScm"})
966
967 mapping = [
968 # option, xml name, default value
969 ("manifest-url", "manifestRepositoryUrl", None),
970 ("jobs", "jobs", 0),
971 ("depth", "depth", 0),
972 ("current-branch", "currentBranch", True),
973 ("reset-first", "resetFirst", False),
974 ("clean-first", "cleanFirst", False),
975 ("quiet", "quiet", True),
976 ("force-sync", "forceSync", False),
977 ("no-tags", "noTags", False),
978 ("trace", "trace", False),
979 ("show-all-changes", "showAllChanges", False),
980 ]
981 helpers.convert_mapping_to_xml(scm, data, mapping, fail_required=True)
982
983 optional_mapping = [
984 # option, xml name, default value
985 ("manifest-branch", "manifestBranch", None),
986 ("manifest-file", "manifestFile", None),
987 ("manifest-group", "manifestGroup", None),
988 ("destination-dir", "destinationDir", None),
989 ("repo-url", "repoUrl", None),
990 ("mirror-dir", "mirrorDir", None),
991 ("local-manifest", "localManifest", None),
992 ]
993 helpers.convert_mapping_to_xml(scm, data, optional_mapping, fail_required=False)
994
995 # ignore-projects does not follow the same pattern of the other parameters,
996 # so process it here:
997 ip = XML.SubElement(scm, "ignoreProjects", {"class": "linked-hash-set"})
998 ignored_projects = data.get("ignore-projects", [""])
999 for ignored_project in ignored_projects:
1000 XML.SubElement(ip, "string").text = str(ignored_project)
1001
1002
1003 def store(registry, xml_parent, data):
1004 """yaml: store
1005 Specifies the Visualworks Smalltalk Store repository for this job.
1006
1007 Requires the Jenkins :jenkins-plugins:`Visualworks Smalltalk Store Plugin
1008 <visualworks-store>`.
1009
1010 :arg str script: name of the Store script to run
1011 :arg str repository: name of the Store repository
1012 :arg str version-regex: regular expression that specifies which pundle
1013 versions should be considered (optional)
1014 :arg str minimum-blessing: minimum blessing level to consider (optional)
1015 :arg str parcel-builder-file: name of the file to generate as input to
1016 a later parcel building step (optional - if not specified, then no
1017 parcel builder file will be generated)
1018 :arg list pundles:
1019
1020 :(package or bundle): (`dict`): A package or bundle to check
1021
1022 Example:
1023
1024 .. literalinclude:: /../../tests/scm/fixtures/store001.yaml
1025 """
1026
1027 namespace = "org.jenkinsci.plugins.visualworks_store"
1028 scm = XML.SubElement(xml_parent, "scm", {"class": "{0}.StoreSCM".format(namespace)})
1029 mapping = [("script", "scriptName", None), ("repository", "repositoryName", None)]
1030 helpers.convert_mapping_to_xml(scm, data, mapping, fail_required=True)
1031
1032 pundle_specs = data.get("pundles", [])
1033 if not pundle_specs:
1034 raise JenkinsJobsException("At least one pundle must be specified")
1035 valid_pundle_types = ["PACKAGE", "BUNDLE"]
1036 pundles = XML.SubElement(scm, "pundles")
1037
1038 for pundle_spec in pundle_specs:
1039 pundle = XML.SubElement(pundles, "{0}.PundleSpec".format(namespace))
1040 pundle_type = next(iter(pundle_spec))
1041 pundle_name = pundle_spec[pundle_type]
1042 mapping = [
1043 ("", "name", pundle_name),
1044 ("", "pundleType", pundle_type.upper(), valid_pundle_types),
1045 ]
1046 helpers.convert_mapping_to_xml(pundle, data, mapping, fail_required=True)
1047
1048 generate_parcel = "parcel-builder-file" in data
1049 mapping_optional = [
1050 ("version-regex", "versionRegex", None),
1051 ("minimum-blessing", "minimumBlessingLevel", None),
1052 ("", "generateParcelBuilderInputFile", generate_parcel),
1053 ("parcel-builder-file", "parcelBuilderInputFilename", None),
1054 ]
1055 helpers.convert_mapping_to_xml(scm, data, mapping_optional, fail_required=False)
1056
1057
1058 def svn(registry, xml_parent, data):
1059 """yaml: svn
1060 Specifies the svn SCM repository for this job.
1061
1062 :arg str url: URL of the svn repository
1063 :arg str basedir: location relative to the workspace root to checkout to
1064 (default '.')
1065 :arg str credentials-id: optional argument to specify the ID of credentials
1066 to use
1067 :arg str repo-depth: Repository depth. Can be one of 'infinity', 'empty',
1068 'files', 'immediates' or 'unknown'. (default 'infinity')
1069 :arg bool ignore-externals: Ignore Externals. (default false)
1070 :arg str workspaceupdater: optional argument to specify
1071 :arg str workspaceupdater: optional argument to specify how to update the
1072 workspace (default wipeworkspace)
1073
1074 :supported values:
1075 * **wipeworkspace** - deletes the workspace before checking out
1076 * **revertupdate** - do an svn revert then an svn update
1077 * **emulateclean** - delete unversioned/ignored files then update
1078 * **update** - do an svn update as much as possible
1079
1080 :arg list(str) excluded-users: list of users to ignore revisions from
1081 when polling for changes (if polling is enabled; parameter is optional)
1082 :arg list(str) included-regions: list of file/folders to include
1083 (optional)
1084 :arg list(str) excluded-regions: list of file/folders to exclude (optional)
1085 :arg list(str) excluded-commit-messages: list of commit messages to exclude
1086 (optional)
1087 :arg str exclusion-revprop-name: revision svn-property to ignore (optional)
1088 :arg bool ignore-property-changes-on-directories: ignore svn-property only
1089 changes of directories (default false)
1090 :arg bool filter-changelog: If set Jenkins will apply the same inclusion
1091 and exclusion patterns for displaying changelog entries as it does for
1092 polling for changes (default false)
1093 :arg list repos: list of repositories to checkout (optional)
1094 :arg list additional-credentials: list of additional credentials (optional)
1095 :Additional-Credentials:
1096
1097 * **realm** (`str`) -- realm to use
1098 * **credentials-id** (`str`) -- optional ID of credentials to use
1099
1100 :arg str viewvc-url: URL of the svn web interface (optional)
1101
1102 :Repo:
1103 * **url** (`str`) -- URL for the repository
1104 * **basedir** (`str`) -- Location relative to the workspace root
1105 to checkout to (default '.')
1106 * **credentials-id** - optional ID of credentials to use
1107 * **repo-depth** - Repository depth. Can be one of 'infinity',
1108 'empty', 'files', 'immediates' or 'unknown'. (default 'infinity')
1109 * **ignore-externals** - Ignore Externals. (default false)
1110
1111 Multiple repos example:
1112
1113 .. literalinclude:: /../../tests/scm/fixtures/svn-multiple-repos-001.yaml
1114
1115 Advanced commit filtering example:
1116
1117 .. literalinclude:: /../../tests/scm/fixtures/svn-regions-001.yaml
1118 """
1119 scm = XML.SubElement(xml_parent, "scm", {"class": "hudson.scm.SubversionSCM"})
1120 if "viewvc-url" in data:
1121 browser = XML.SubElement(
1122 scm, "browser", {"class": "hudson.scm.browsers.ViewSVN"}
1123 )
1124 mapping = [("viewvc-url", "url", None)]
1125 helpers.convert_mapping_to_xml(browser, data, mapping, fail_required=True)
1126 locations = XML.SubElement(scm, "locations")
1127
1128 def populate_repo_xml(parent, data):
1129 module = XML.SubElement(parent, "hudson.scm.SubversionSCM_-ModuleLocation")
1130 mapping = [("url", "remote", None), ("basedir", "local", ".")]
1131 helpers.convert_mapping_to_xml(module, data, mapping, fail_required=True)
1132
1133 repo_depths = ["infinity", "empty", "files", "immediates", "unknown"]
1134 mapping_optional = [
1135 ("credentials-id", "credentialsId", None),
1136 ("repo-depth", "depthOption", "infinity", repo_depths),
1137 ("ignore-externals", "ignoreExternalsOption", False),
1138 ]
1139 helpers.convert_mapping_to_xml(
1140 module, data, mapping_optional, fail_required=False
1141 )
1142
1143 if "repos" in data:
1144 repos = data["repos"]
1145 for repo in repos:
1146 populate_repo_xml(locations, repo)
1147 elif "url" in data:
1148 populate_repo_xml(locations, data)
1149 else:
1150 raise JenkinsJobsException("A top level url or repos list must exist")
1151
1152 def populate_additional_credential_xml(parent, data):
1153 module = XML.SubElement(
1154 parent, "hudson.scm.SubversionSCM_-AdditionalCredentials"
1155 )
1156 XML.SubElement(module, "realm").text = data["realm"]
1157 if "credentials-id" in data:
1158 XML.SubElement(module, "credentialsId").text = data["credentials-id"]
1159
1160 if "additional-credentials" in data:
1161 additional_credentials = XML.SubElement(scm, "additionalCredentials")
1162 additional_credentials_data = data["additional-credentials"]
1163
1164 for additional_credential in additional_credentials_data:
1165 populate_additional_credential_xml(
1166 additional_credentials, additional_credential
1167 )
1168
1169 updater = data.get("workspaceupdater", "wipeworkspace")
1170 if updater == "wipeworkspace":
1171 updaterclass = "CheckoutUpdater"
1172 elif updater == "revertupdate":
1173 updaterclass = "UpdateWithRevertUpdater"
1174 elif updater == "emulateclean":
1175 updaterclass = "UpdateWithCleanUpdater"
1176 elif updater == "update":
1177 updaterclass = "UpdateUpdater"
1178 XML.SubElement(
1179 scm, "workspaceUpdater", {"class": "hudson.scm.subversion." + updaterclass}
1180 )
1181
1182 mapping = [
1183 # option, xml name, default value
1184 ("excluded-regions", "excludedRegions", []),
1185 ("included-regions", "includedRegions", []),
1186 ("excluded-users", "excludedUsers", []),
1187 ("exclusion-revprop-name", "excludedRevprop", ""),
1188 ("excluded-commit-messages", "excludedCommitMessages", []),
1189 ("ignore-property-changes-on-directories", "ignoreDirPropChanges", False),
1190 ("filter-changelog", "filterChangelog", False),
1191 ]
1192
1193 for optname, xmlname, defvalue in mapping:
1194 if isinstance(defvalue, list):
1195 val = "\n".join(data.get(optname, defvalue))
1196 else:
1197 val = data.get(optname, defvalue)
1198 # Skip adding xml entry if default is empty and no value given
1199 if not val and (defvalue in ["", []]):
1200 continue
1201
1202 xe = XML.SubElement(scm, xmlname)
1203 if isinstance(defvalue, bool):
1204 xe.text = str(val).lower()
1205 else:
1206 xe.text = str(val)
1207
1208
1209 def tfs(registry, xml_parent, data):
1210 r"""yaml: tfs
1211 Specifies the Team Foundation Server repository for this job.
1212
1213 Requires the Jenkins Team Foundation Server Plugin
1214 (:jenkins-github:`tfs-plugin`).
1215
1216 **NOTE**: TFS Password must be entered manually on the project if a
1217 user name is specified. The password will be overwritten with an empty
1218 value every time the job is rebuilt with Jenkins Job Builder.
1219
1220 :arg str server-url: The name or URL of the team foundation server.
1221 If the server has been registered on the machine then it is only
1222 necessary to enter the name.
1223 :arg str project-path: The name of the project as it is registered on the
1224 server.
1225 :arg str login: The user name that is registered on the server. The user
1226 name must contain the name and the domain name. Entered as
1227 domain\\\\user or user\@domain (optional).
1228 **NOTE**: You must enter in at least two slashes for the
1229 domain\\\\user format in JJB YAML. It will be rendered normally.
1230 :arg str use-update: If true, Hudson will not delete the workspace at end
1231 of each build. This causes the artifacts from the previous build to
1232 remain when a new build starts. (default true)
1233 :arg str local-path: The folder where all files will be retrieved into.
1234 The folder name is a relative path, under the workspace of the current
1235 job. (default .)
1236 :arg str workspace: The name of the workspace under which the source
1237 should be retrieved. This workspace is created at the start of a
1238 download, and deleted at the end. You can normally omit the property
1239 unless you want to name a workspace to avoid conflicts on the server
1240 (i.e. when you have multiple projects on one server talking to a
1241 Team Foundation Server). (default Hudson-${JOB_NAME}-${NODE_NAME})
1242
1243 The TFS plugin supports the following macros that are replaced in the
1244 workspace name:
1245
1246 * ${JOB_NAME} - The name of the job.
1247 * ${USER_NAME} - The user name that the Hudson server or slave is
1248 running as.
1249 * ${NODE_NAME} - The name of the node/slave that the plugin currently
1250 is executed on. Note that this is not the hostname, this value is
1251 the Hudson configured name of the slave/node.
1252 * ${ENV} - The environment variable that is set on the master or slave.
1253
1254
1255 :arg dict web-access: Adds links in "changes" views within Jenkins to an
1256 external system for browsing the details of those changes. The "Auto"
1257 selection attempts to infer the repository browser from other jobs,
1258 if supported by the SCM and a job with matching SCM details can be
1259 found. (optional, default Auto).
1260
1261 :web-access value:
1262 * **web-url** -- Enter the URL to the TSWA server. The plugin will
1263 strip the last path (if any) of the URL when building URLs for
1264 change set pages and other pages. (optional, default
1265 uses server-url)
1266
1267
1268 Examples:
1269
1270 .. literalinclude:: /../../tests/scm/fixtures/tfs-001.yaml
1271
1272 .. literalinclude:: /../../tests/scm/fixtures/tfs-002.yaml
1273
1274 """
1275
1276 tfs = XML.SubElement(
1277 xml_parent, "scm", {"class": "hudson.plugins.tfs." "TeamFoundationServerScm"}
1278 )
1279 mapping = [
1280 ("server-url", "serverUrl", ""),
1281 ("project-path", "projectPath", ""),
1282 ("local-path", "localPath", "."),
1283 ("workspace", "workspaceName", "Hudson-${JOB_NAME}-${NODE_NAME}"),
1284 # TODO: In the future, it would be nice to have a place that can pull
1285 # passwords into JJB without having to commit them in plaintext. This
1286 # could also integrate nicely with global configuration options.
1287 ("", "userPassword", ""),
1288 ("login", "userName", ""),
1289 ("use-update", "useUpdate", True),
1290 ]
1291 helpers.convert_mapping_to_xml(tfs, data, mapping, fail_required=True)
1292
1293 store = data.get("web-access", None)
1294 if isinstance(store, list):
1295 web = XML.SubElement(
1296 tfs,
1297 "repositoryBrowser",
1298 {"class": "hudson.plugins.tfs.browsers." "TeamSystemWebAccessBrowser"},
1299 )
1300 XML.SubElement(web, "url").text = str(store[0].get("web-url", None))
1301 elif "web-access" in data and store is None:
1302 XML.SubElement(
1303 tfs,
1304 "repositoryBrowser",
1305 {
1306 "class": "hudson."
1307 "plugins.tfs.browsers."
1308 "TeamSystemWebAccess"
1309 "Browser"
1310 },
1311 )
1312
1313
1314 def workspace(registry, xml_parent, data):
1315 """yaml: workspace
1316 Specifies the cloned workspace for this job to use as a SCM source.
1317
1318 Requires the Jenkins :jenkins-plugins:`Clone Workspace SCM Plugin
1319 <clone-workspace-scm>`.
1320
1321 The job the workspace is cloned from must be configured with an
1322 clone-workspace publisher
1323
1324 :arg str parent-job: The name of the parent job to clone the
1325 workspace from.
1326 :arg str criteria: Set the criteria to determine what build of the parent
1327 project to use. Can be one of 'Any', 'Not Failed' or 'Successful'.
1328 (default Any)
1329
1330
1331 Example:
1332
1333 .. literalinclude:: /../../tests/scm/fixtures/workspace001.yaml
1334 """
1335
1336 workspace = XML.SubElement(
1337 xml_parent,
1338 "scm",
1339 {"class": "hudson.plugins." "cloneworkspace.CloneWorkspaceSCM"},
1340 )
1341 criteria_list = ["Any", "Not Failed", "Successful"]
1342
1343 criteria = data.get("criteria", "Any").title()
1344
1345 mapping = [
1346 ("parent-job", "parentJobName", ""),
1347 ("", "criteria", criteria, criteria_list),
1348 ]
1349 helpers.convert_mapping_to_xml(workspace, data, mapping, fail_required=True)
1350
1351
1352 def hg(self, xml_parent, data):
1353 """yaml: hg
1354 Specifies the mercurial SCM repository for this job.
1355
1356 Requires the Jenkins :jenkins-plugins:`Mercurial Plugin <mercurial>`.
1357
1358 :arg str url: URL of the hg repository (required)
1359 :arg str credentials-id: ID of credentials to use to connect (optional)
1360 :arg str revision-type: revision type to use (default 'branch')
1361 :arg str revision: the branch or tag name you would like to track
1362 (default 'default')
1363 :arg list(str) modules: reduce unnecessary builds by specifying a list of
1364 "modules" within the repository. A module is a directory name within
1365 the repository that this project lives in. (default '')
1366 :arg bool clean: wipe any local modifications or untracked files in the
1367 repository checkout (default false)
1368 :arg str subdir: check out the Mercurial repository into this
1369 subdirectory of the job's workspace (optional)
1370 :arg bool disable-changelog: do not calculate the Mercurial changelog
1371 for each build (default false)
1372 :arg str browser: what repository browser to use
1373
1374 :browsers supported:
1375 * **auto** - (default)
1376 * **bitbucketweb** - https://bitbucket.org/
1377 * **fisheye** - https://www.atlassian.com/software/fisheye
1378 * **googlecode** - https://code.google.com/
1379 * **hgweb** - https://repo.mercurial-scm.org/hg/help/hgweb
1380 * **kilnhg** - https://ignitetech.com/softwarelibrary/fogbugz
1381 * **rhodecode** - https://rhodecode.com/ (versions >= 1.2)
1382 * **rhodecode-pre-1.2.0** - https://rhodecode.com/ (versions < 1.2)
1383
1384 :arg str browser-url: url for the repository browser
1385 (required if browser is set)
1386
1387
1388 Example:
1389
1390 .. literalinclude:: ../../tests/scm/fixtures/hg02.yaml
1391 """
1392
1393 revision_type_dict = {"branch": "BRANCH", "tag": "TAG"}
1394 browser = data.get("browser", "auto")
1395 browserdict = {
1396 "auto": "",
1397 "bitbucket": "BitBucket", # deprecated
1398 "bitbucketweb": "BitBucket",
1399 "fisheye": "FishEye",
1400 "googlecode": "GoogleCode",
1401 "hgweb": "HgWeb",
1402 "kilnhg": "KilnHG",
1403 "rhodecode": "RhodeCode",
1404 "rhodecode-pre-1.2.0": "RhodeCodeLegacy",
1405 }
1406
1407 scm = XML.SubElement(
1408 xml_parent, "scm", {"class": "hudson.plugins.mercurial.MercurialSCM"}
1409 )
1410 mapping = [("url", "source", None)]
1411 helpers.convert_mapping_to_xml(scm, data, mapping, fail_required=True)
1412
1413 mapping_optional = [
1414 ("credentials-id", "credentialsId", None),
1415 ("revision-type", "revisionType", "branch", revision_type_dict),
1416 ("revision", "revision", "default"),
1417 ("subdir", "subdir", None),
1418 ("clean", "clean", False),
1419 ]
1420 helpers.convert_mapping_to_xml(scm, data, mapping_optional, fail_required=False)
1421
1422 modules = data.get("modules", "")
1423 if isinstance(modules, list):
1424 modules = " ".join(modules)
1425 XML.SubElement(scm, "modules").text = modules
1426 XML.SubElement(scm, "disableChangeLog").text = str(
1427 data.get("disable-changelog", False)
1428 ).lower()
1429
1430 if browser != "auto":
1431 bc = XML.SubElement(
1432 scm,
1433 "browser",
1434 {"class": "hudson.plugins.mercurial.browser." + browserdict[browser]},
1435 )
1436 mapping = [("browser-url", "url", None, browserdict[browser])]
1437 helpers.convert_mapping_to_xml(bc, data, mapping, fail_required=True)
1438
1439
1440 def openshift_img_streams(registry, xml_parent, data):
1441 r"""yaml: openshift-img-streams
1442 Rather than a Build step extension plugin, this is an extension of the
1443 Jenkins SCM plugin, where this baked-in polling mechanism provided by
1444 Jenkins is leveraged by exposing some of the common semantics between
1445 OpenShift ImageStreams (which are abstractions of Docker repositories)
1446 and SCMs - versions / commit IDs of related artifacts
1447 (images vs. programmatics files)
1448
1449 Requires the Jenkins :jenkins-plugins:`OpenShift Pipeline Plugin
1450 <openshift-pipeline>`.
1451
1452 :arg str image-stream-name: The name of the ImageStream is what shows up
1453 in the NAME column if you dump all the ImageStream's with the
1454 `oc get is` command invocation. (default nodejs-010-centos7)
1455 :arg str tag: The specific image tag within the ImageStream to monitor.
1456 (default latest)
1457 :arg str api-url: This would be the value you specify if you leverage the
1458 --server option on the OpenShift `oc` command.
1459 (default \https://openshift.default.svc.cluster.local\)
1460 :arg str namespace: The value here should be whatever was the output
1461 form `oc project` when you created the BuildConfig you want to run
1462 a Build on. (default test)
1463 :arg str auth-token: The value here is what you supply with the --token
1464 option when invoking the OpenShift `oc` command. (default '')
1465 :arg bool verbose: This flag is the toggle for
1466 turning on or off detailed logging in this plug-in. (default false)
1467
1468 Full Example:
1469
1470 .. literalinclude::
1471 ../../tests/scm/fixtures/openshift-img-streams001.yaml
1472 :language: yaml
1473
1474 Minimal Example:
1475
1476 .. literalinclude::
1477 ../../tests/scm/fixtures/openshift-img-streams002.yaml
1478 :language: yaml
1479 """
1480 scm = XML.SubElement(
1481 xml_parent,
1482 "scm",
1483 {"class": "com.openshift.jenkins.plugins.pipeline." "OpenShiftImageStreams"},
1484 )
1485 mapping = [
1486 # option, xml name, default value
1487 ("image-stream-name", "imageStreamName", "nodejs-010-centos7"),
1488 ("tag", "tag", "latest"),
1489 ("api-url", "apiURL", "https://openshift.default.svc.cluster.local"),
1490 ("namespace", "namespace", "test"),
1491 ("auth-token", "authToken", ""),
1492 ("verbose", "verbose", False),
1493 ]
1494 helpers.convert_mapping_to_xml(scm, data, mapping, fail_required=True)
1495
1496
1497 def bzr(registry, xml_parent, data):
1498 """yaml: bzr
1499 Specifies the bzr SCM repository for this job.
1500
1501 Requires the Jenkins :jenkins-plugins:`Bazaar Plugin <bazaar>`.
1502
1503 :arg str url: URL of the bzr branch (required)
1504 :arg bool clean-tree: Clean up the workspace (using bzr) before pulling
1505 the branch (default false)
1506 :arg bool lightweight-checkout: Use a lightweight checkout instead of a
1507 full branch (default false)
1508 :arg str browser: The repository browser to use.
1509
1510 :browsers supported:
1511 * **auto** - (default)
1512 * **loggerhead** - as used by Launchpad
1513 * **opengrok** - https://opengrok.github.io/OpenGrok/
1514
1515 :arg str browser-url:
1516 URL for the repository browser (required if browser is set).
1517
1518 :arg str opengrok-root-module:
1519 Root module for OpenGrok (required if browser is opengrok).
1520
1521 Example:
1522
1523 .. literalinclude:: /../../tests/scm/fixtures/bzr001.yaml
1524 :language: yaml
1525 """
1526 mapping = [
1527 # option, xml name, default value (text), attributes (hard coded)
1528 ("url", "source", None),
1529 ("clean-tree", "cleantree", False),
1530 ("lightweight-checkout", "checkout", False),
1531 ]
1532 scm_element = XML.SubElement(
1533 xml_parent, "scm", {"class": "hudson.plugins.bazaar.BazaarSCM"}
1534 )
1535 helpers.convert_mapping_to_xml(scm_element, data, mapping, fail_required=True)
1536
1537 browser_name_to_class = {"loggerhead": "Loggerhead", "opengrok": "OpenGrok"}
1538 browser = data.get("browser", "auto")
1539 if browser == "auto":
1540 return
1541 if browser not in browser_name_to_class:
1542 raise InvalidAttributeError("browser", browser, browser_name_to_class.keys())
1543 browser_element = XML.SubElement(
1544 scm_element,
1545 "browser",
1546 {
1547 "class": "hudson.plugins.bazaar.browsers.{0}".format(
1548 browser_name_to_class[browser]
1549 )
1550 },
1551 )
1552 mapping = [("browser-url", "url", None)]
1553 helpers.convert_mapping_to_xml(browser_element, data, mapping, fail_required=True)
1554
1555 if browser == "opengrok":
1556 mapping = [("opengrok-root-module", "rootModule", None)]
1557 helpers.convert_mapping_to_xml(
1558 browser_element, data, mapping, fail_required=True
1559 )
1560
1561
1562 def url(registry, xml_parent, data):
1563 """yaml: url
1564
1565 Watch for changes in, and download an artifact from a particular url.
1566
1567 Requires the Jenkins :jenkins-plugins:`URL SCM <URLSCM>`.
1568
1569 :arg list url-list: List of URLs to watch. (required)
1570 :arg bool clear-workspace: If set to true, clear the workspace before
1571 downloading the artifact(s) specified in url-list. (default false)
1572
1573 Examples:
1574
1575 .. literalinclude:: ../../tests/scm/fixtures/url001.yaml
1576 :language: yaml
1577 .. literalinclude:: ../../tests/scm/fixtures/url002.yaml
1578 :language: yaml
1579 """
1580
1581 scm = XML.SubElement(xml_parent, "scm", {"class": "hudson.plugins.URLSCM.URLSCM"})
1582 urls = XML.SubElement(scm, "urls")
1583 for data_url in data["url-list"]:
1584 url_tuple = XML.SubElement(urls, "hudson.plugins.URLSCM.URLSCM_-URLTuple")
1585 mapping = [("", "urlString", data_url)]
1586 helpers.convert_mapping_to_xml(url_tuple, data, mapping, fail_required=True)
1587 mapping = [("clear-workspace", "clearWorkspace", False)]
1588 helpers.convert_mapping_to_xml(scm, data, mapping, fail_required=True)
1589
1590
1591 def dimensions(registry, xml_parent, data):
1592 """yaml: dimensions
1593
1594 Specifies the Dimensions SCM repository for this job.
1595
1596 Requires Jenkins :jenkins-plugins:`Dimensions Plugin <dimensionsscm>`.
1597
1598 :arg str project: Project name of format PRODUCT_ID:PROJECT_NAME (required)
1599 :arg str permissions: Default Permissions for updated files
1600 (default: DEFAULT)
1601
1602 :Permissions:
1603 * **DEFAULT**
1604 * **READONLY**
1605 * **WRITABLE**
1606 :arg str eol: End of line (default: DEFAULT)
1607
1608 :End of line:
1609 * **DEFAULT**
1610 * **UNIX**
1611 * **WINDOWS**
1612 * **UNCHANGED**
1613 :arg list folders: Folders to monitor (default /)
1614 :arg list exclude: Paths to exclude from monitor
1615 :arg str username: Repository username for this job
1616 :arg str password: Repository password for this job
1617 :arg str server: Dimensions server for this job
1618 :arg str database: Dimensions database for this job.
1619 Format must be database@dsn
1620 :arg bool update: Use update (default false)
1621 :arg bool clear-workspace: Clear workspace prior to build (default false)
1622 :arg bool force-build: Force build even if the repository SCM checkout
1623 operation fails (default false)
1624 :arg bool overwrite-modified: Overwrite files in worspace from
1625 repository files (default false)
1626 :arg bool expand-vars: Expand substitution variables (default false)
1627 :arg bool no-metadata: Checkout files with no metadata (default false)
1628 :arg bool maintain-timestamp: Maintain file timestamp from Dimensions
1629 (default false)
1630 :arg bool slave-checkout: Force slave based checkout (default false)
1631 :arg str timezone: Server timezone
1632 :arg str web-url: Dimensions Web URL
1633
1634 Examples:
1635
1636 .. literalinclude:: /../../tests/scm/fixtures/dimensions-minimal.yaml
1637 :language: yaml
1638 .. literalinclude:: /../../tests/scm/fixtures/dimensions-full.yaml
1639 :language: yaml
1640
1641 """
1642
1643 scm = XML.SubElement(
1644 xml_parent, "scm", {"class": "hudson.plugins.dimensionsscm.DimensionsSCM"}
1645 )
1646
1647 # List to check against for valid permission
1648 perm = ["DEFAULT", "READONLY", "WRITABLE"]
1649
1650 # List to check against for valid end of line
1651 eol = ["DEFAULT", "UNIX", "WINDOWS", "UNCHANGED"]
1652
1653 mapping = [
1654 # option, xml name, default value (text), attributes (hard coded)
1655 ("project", "project", None),
1656 ("permissions", "permissions", "DEFAULT", perm),
1657 ("eol", "eol", "DEFAULT", eol),
1658 ("update", "canJobUpdate", False),
1659 ("clear-workspace", "canJobDelete", False),
1660 ("force-build", "canJobForce", False),
1661 ("overwrite-modified", "canJobRevert", False),
1662 ("expand-vars", "canJobExpand", False),
1663 ("no-metadata", "canJobNoMetadata", False),
1664 ("maintain-timestamp", "canJobNoTouch", False),
1665 ("slave-checkout", "forceAsSlave", False),
1666 ]
1667 helpers.convert_mapping_to_xml(scm, data, mapping, fail_required=True)
1668
1669 # Folders to monitor. Default '/'
1670 folders = XML.SubElement(scm, "folders")
1671 if "folders" in data:
1672 for folder in data["folders"]:
1673 XML.SubElement(folders, "string").text = folder
1674 else:
1675 XML.SubElement(folders, "string").text = "/"
1676
1677 # Excluded paths
1678 exclude = XML.SubElement(scm, "pathsToExclude")
1679 if "exclude" in data:
1680 for exc in data["exclude"]:
1681 XML.SubElement(exclude, "string").text = exc
1682
1683 optional_mapping = [
1684 # option, xml name, default value (text), attributes (hard coded)
1685 ("username", "jobUserName", None),
1686 ("password", "jobPasswd", None),
1687 ("server", "jobServer", None),
1688 ("database", "jobDatabase", None),
1689 ("timezone", "jobTimeZone", None),
1690 ("web-url", "jobWebUrl", None),
1691 ]
1692 helpers.convert_mapping_to_xml(scm, data, optional_mapping, fail_required=False)
1693
1694
1695 def accurev(registry, xml_parent, data):
1696 """yaml: accurev
1697 Specifies the AccuRev SCM repository for this job.
1698
1699 Requires the Jenkins :jenkins-plugins:`AccuRev Plugin <accurev>`.
1700
1701 :arg str depot: Depot you want to use for the current job (optional)
1702 :arg str stream: Stream where the build will be generated from (optional)
1703 :arg str server-name: AccuRev server you are using
1704 for your builds (required)
1705 :arg bool ignore-parent-changes: Ignore possibility
1706 of changes in the parent stream (default false)
1707 :arg bool clean-reference-tree: Deletes any external files
1708 in reference tree (default false)
1709 :arg bool build-from-snapshot: Creates snapshot
1710 of the target stream, then populates and
1711 builds from that snapshot (default false)
1712 :arg bool do-not-pop-content: If checkbox is on, elements
1713 are not populating vice versa (default false)
1714 :arg str workspace: Name of existing workspace (optional)
1715 :arg str reference-tree: Name of the reference tree (optional)
1716 :arg str directory-offset: Relative directory path from
1717 the default Jenkins workspace location
1718 where the files from the stream, workspace,
1719 or reference tree should be retrieved from. (optional)
1720 :arg str sub-path: Makes a "best effort" to ensure
1721 that only the sub-path is populated (optional)
1722 :arg str filter-poll-scm: Specify directories or
1723 files you want Jenkins to check before starting a build (optional)
1724 :arg str snapshot-name-format: Naming conventions
1725 for the snapshot in this field (optional)
1726
1727 Example:
1728
1729 .. literalinclude:: /../../tests/scm/fixtures/accurev001.yaml
1730 """
1731 scm = XML.SubElement(
1732 xml_parent, "scm", {"class": "hudson.plugins.accurev.AccurevSCM"}
1733 )
1734 mapping = [
1735 ("depot", "depot", None),
1736 ("stream", "stream", None),
1737 ("server-name", "serverName", None),
1738 ("ignore-parent-changes", "ignoreStreamParent", False),
1739 ("clean-reference-tree", "cleanreftree", False),
1740 ("build-from-snapshot", "useSnapshot", False),
1741 ("do-not-pop-content", "dontPopContent", False),
1742 ]
1743 helpers.convert_mapping_to_xml(scm, data, mapping, fail_required=True)
1744
1745 additional_mapping = [
1746 ("workspace", "workspace", None),
1747 ("reference-tree", "reftree", None),
1748 ("directory-offset", "directoryOffset", None),
1749 ("sub-path", "subPath", None),
1750 ("filter-poll-scm", "filterForPollSCM", None),
1751 ("snapshot-name-format", "snapshotNameFormat", None),
1752 ]
1753 helpers.convert_mapping_to_xml(scm, data, additional_mapping, fail_required=False)
1754
1755
1756 class SCM(jenkins_jobs.modules.base.Base):
1757 sequence = 30
1758
1759 component_type = "scm"
1760 component_list_type = "scm"
1761
1762 def gen_xml(self, xml_parent, data):
1763
1764 # multibranch-pipeline scm implementation is incompatible with SCM
1765 if data.get("project-type") in [
1766 "githuborg",
1767 "multibranch",
1768 "multibranch-defaults",
1769 "pipeline",
1770 ]:
1771 logging.debug(
1772 "SCM Module skipped for %s project-type." % data.get("project-type")
1773 )
1774 return
1775
1776 scms_parent = XML.Element("scms")
1777 component_list = data.get("scm", [])
1778 self.dispatch_component_list("scm", component_list, scms_parent)
1779 scms_count = len(scms_parent)
1780 if scms_count == 0:
1781 XML.SubElement(xml_parent, "scm", {"class": "hudson.scm.NullSCM"})
1782 elif scms_count == 1:
1783 xml_parent.append(scms_parent[0])
1784 else:
1785 class_name = "org.jenkinsci.plugins.multiplescms.MultiSCM"
1786 xml_attribs = {"class": class_name}
1787 xml_parent = XML.SubElement(xml_parent, "scm", xml_attribs)
1788
1789 for scms_child in scms_parent:
1790 try:
1791 scms_child.tag = scms_child.attrib["class"]
1792 del scms_child.attrib["class"]
1793 except KeyError:
1794 pass
1795
1796 xml_parent.append(scms_parent)
1797
1798
1799 class PipelineSCM(jenkins_jobs.modules.base.Base):
1800 sequence = 30
1801
1802 component_type = "pipeline-scm"
1803 component_list_type = "pipeline-scm"
1804
1805 def gen_xml(self, xml_parent, data):
1806 definition_parent = xml_parent.find("definition")
1807 pipeline_dict = data.get(self.component_type, {})
1808 scms = pipeline_dict.get("scm")
1809 if scms:
1810 scms_count = len(scms)
1811 if scms_count == 0:
1812 raise JenkinsJobsException("'scm' missing or empty")
1813 elif scms_count == 1:
1814 component = scms[0]
1815 if isinstance(scms, LocList):
1816 component_pos = scms.value_pos[0]
1817 else:
1818 component_pos = None
1819 self.registry.dispatch(
1820 "scm", definition_parent, component, component_pos=component_pos
1821 )
1822 mapping = [
1823 ("script-path", "scriptPath", "Jenkinsfile"),
1824 ("lightweight-checkout", "lightweight", None, [True, False]),
1825 ]
1826 helpers.convert_mapping_to_xml(
1827 definition_parent, pipeline_dict, mapping, fail_required=False
1828 )
1829 else:
1830 raise JenkinsJobsException(
1831 "Only one SCM can be specified " "as pipeline-scm"
1832 )