Debian Codegraph @

jenkins_jobs/modules/project_githuborg.py

raw
1 # -*- coding: utf-8 -*-
2 # Copyright (C) 2021 The Linux Foundation
3 #
4 # Licensed under the Apache License, Version 2.0 (the "License");
5 # you may not use this file except in compliance with the License.
6 # You may obtain a copy of the License at
7 #
8 # http://www.apache.org/licenses/LICENSE-2.0
9 #
10 # Unless required by applicable law or agreed to in writing, software
11 # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12 # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 # License for the specific language governing permissions and limitations
14 # under the License.
15
16
17 """
18 The Github Organization project module handles creating Jenkins Github
19 Organization jobs, which are made up of multibranch pipelines for all
20 repositories containing the specified Jenkinsfile(s).
21 You may specify ``githuborg`` in the ``project-type`` attribute of
22 the :ref:`Job` definition.
23
24 Plugins required:
25
26 * :jenkins-plugins:`GitHub Branch Source Plugin <github-branch-source>`
27
28 :Job Parameters:
29
30 * **github-org** (`dict`): Refer to
31 :func:`github_org <github_org>` for documentation.
32
33 * **periodic-folder-trigger** (`str`): How often to scan for new branches
34 or pull/change requests. Valid values: 1m, 2m, 5m, 10m, 15m, 20m, 25m,
35 30m, 1h, 2h, 4h, 8h, 12h, 1d, 2d, 1w, 2w, 4w. (default none)
36 * **prune-dead-branches** (`bool`): If dead branches upon check should
37 result in their job being dropped. (default true)
38 * **number-to-keep** (`int`): How many builds should be kept.
39 (default '-1, all')
40 * **days-to-keep** (`int`): For how many days should a build be kept.
41 (default '-1, forever')
42 * **script-path** (`str`): Path to Jenkinsfile, relative to workspace.
43 (default 'Jenkinsfile')
44
45 Job examples:
46
47 .. literalinclude:: /../../tests/githuborg/fixtures/minimal.yaml
48
49 .. literalinclude:: /../../tests/githuborg/fixtures/githuborg-job-full.yaml
50
51 """
52 import collections
53 import logging
54 import xml.etree.ElementTree as XML
55 import jenkins_jobs.modules.base
56 import jenkins_jobs.modules.helpers as helpers
57 import jenkins_jobs.modules.project_multibranch as multibranch
58
59 from jenkins_jobs.modules.scm import git_extensions
60 from jenkins_jobs.errors import InvalidAttributeError
61
62 logger = logging.getLogger(str(__name__))
63
64
65 class GithubOrganization(jenkins_jobs.modules.base.Base):
66 sequence = 0
67 jenkins_class = "jenkins.branch.OrganizationFolder"
68
69 def root_xml(self, data):
70 xml_parent = XML.Element(self.jenkins_class)
71 xml_parent.attrib["plugin"] = "branch-api"
72 XML.SubElement(xml_parent, "properties")
73
74 ################
75 # Folder Views #
76 ################
77
78 folderViews = XML.SubElement(
79 xml_parent,
80 "folderViews",
81 {"class": "jenkins.branch.OrganizationFolderViewHolder"},
82 )
83
84 XML.SubElement(folderViews, "owner", {"reference": "../.."})
85
86 ##################
87 # Health Metrics #
88 ##################
89
90 hm = XML.SubElement(xml_parent, "healthMetrics")
91 hm_path = "com.cloudbees.hudson.plugins.folder.health" ".WorstChildHealthMetric"
92 hm_plugin = XML.SubElement(hm, hm_path, {"plugin": "cloudbees-folder"})
93 XML.SubElement(hm_plugin, "nonRecursive").text = "false"
94
95 ########
96 # Icon #
97 ########
98
99 icon = XML.SubElement(
100 xml_parent, "icon", {"class": "jenkins.branch.MetadataActionFolderIcon"}
101 )
102 XML.SubElement(
103 icon, "owner", {"class": self.jenkins_class, "reference": "../.."}
104 )
105
106 ########################
107 # Orphan Item Strategy #
108 ########################
109
110 ois_default_strategy = (
111 "com.cloudbees.hudson.plugins."
112 "folder.computed.DefaultOrphanedItemStrategy"
113 )
114 ois = XML.SubElement(
115 xml_parent,
116 "orphanedItemStrategy",
117 {"class": ois_default_strategy, "plugin": "cloudbees-folder"},
118 )
119
120 ois_mapping = [
121 ("prune-dead-branches", "pruneDeadBranches", True, [True, False]),
122 ("days-to-keep", "daysToKeep", -1),
123 ("number-to-keep", "numToKeep", -1),
124 ]
125 helpers.convert_mapping_to_xml(ois, data, ois_mapping)
126
127 ###########################
128 # Periodic Folder Trigger #
129 ###########################
130
131 triggers = XML.SubElement(xml_parent, "triggers")
132
133 # Valid options for the periodic trigger interval.
134 pft_map = collections.OrderedDict(
135 [
136 ("1m", ("* * * * *", "60000")),
137 ("2m", ("*/2 * * * *", "120000")),
138 ("5m", ("*/5 * * * *", "300000")),
139 ("10m", ("H/6 * * * *", "600000")),
140 ("15m", ("H/6 * * * *", "900000")),
141 ("20m", ("H/3 * * * *", "1200000")),
142 ("25m", ("H/3 * * * *", "1500000")),
143 ("30m", ("H/2 * * * *", "1800000")),
144 ("1h", ("H * * * *", "3600000")),
145 ("2h", ("H * * * *", "7200000")),
146 ("4h", ("H * * * *", "14400000")),
147 ("8h", ("H * * * *", "28800000")),
148 ("12h", ("H H * * *", "43200000")),
149 ("1d", ("H H * * *", "86400000")),
150 ("2d", ("H H * * *", "172800000")),
151 ("1w", ("H H * * *", "604800000")),
152 ("2w", ("H H * * *", "1209600000")),
153 ("4w", ("H H * * *", "2419200000")),
154 ]
155 )
156
157 pft_val = data.get("periodic-folder-trigger")
158 if pft_val:
159 if not pft_map.get(pft_val):
160 raise InvalidAttributeError(
161 "periodic-folder-trigger", pft_val, pft_map.keys()
162 )
163
164 pft_path = (
165 "com.cloudbees.hudson.plugins.folder.computed." "PeriodicFolderTrigger"
166 )
167 pft = XML.SubElement(triggers, pft_path, {"plugin": "cloudbees-folder"})
168 XML.SubElement(pft, "spec").text = pft_map[pft_val][0]
169 XML.SubElement(pft, "interval").text = pft_map[pft_val][1]
170
171 ##############
172 # Navigators #
173 ##############
174
175 navigators = XML.SubElement(xml_parent, "navigators")
176 navigators_plugin = XML.SubElement(
177 navigators,
178 "org.jenkinsci.plugins.github__branch__source.GitHubSCMNavigator",
179 {"plugin": "github-branch-source"},
180 )
181 github_org(navigators_plugin, data.get("github-org"))
182
183 ###########
184 # Factory #
185 ###########
186
187 fopts_map = [("script-path", "scriptPath", "Jenkinsfile")]
188
189 project_factories = XML.SubElement(xml_parent, "projectFactories")
190 factory = XML.SubElement(
191 project_factories,
192 "org.jenkinsci.plugins.workflow.multibranch.WorkflowMultiBranchProjectFactory",
193 {"plugin": "workflow-multibranch"},
194 )
195 helpers.convert_mapping_to_xml(factory, data, fopts_map, fail_required=False)
196
197 ####################
198 # Build Strategies #
199 ####################
200
201 if data.get("github-org").get("build-strategies", None):
202 multibranch.build_strategies(xml_parent, data.get("github-org"))
203
204 return xml_parent
205
206
207 def github_org(xml_parent, data):
208 r"""Configure GitHub Organization and SCM settings.
209
210 :arg str repo-owner: Specify the name of the GitHub Organization or
211 GitHub User Account. (required)
212 :arg str api-uri: The GitHub API uri for hosted / on-site GitHub. Must
213 first be configured in Global Configuration. (default GitHub)
214 :arg str branch-discovery: Discovers branches on the repository.
215 Valid options: no-pr, only-pr, all, false. (default 'no-pr')
216 :arg str repo-name-regex: Regular expression used to match repository names
217 within the organization. (optional)
218 Requires the :jenkins-plugins:`SCM API plugin <scm-api>`.
219 :arg list build-strategies: Provides control over whether to build a branch
220 (or branch like things such as change requests and tags) whenever it is
221 discovered initially or a change from the previous revision has been
222 detected. (optional)
223 Refer to :func:`~build_strategies <project_multibranch.build_strategies>`.
224 :arg str credentials-id: Credentials used to scan branches and pull
225 requests, check out sources and mark commit statuses. (optional)
226 :arg str discover-pr-forks-strategy: Fork strategy. Valid options:
227 merge-current, current, both, false. (default 'merge-current')
228 :arg str discover-pr-forks-trust: Discovers pull requests where the origin
229 repository is a fork of the target repository.
230 Valid options: contributors, everyone, permission or nobody.
231 (default 'contributors')
232 :arg str discover-pr-origin: Discovers pull requests where the origin
233 repository is the same as the target repository.
234 Valid options: merge-current, current, both, false. (default 'merge-current')
235 :arg bool discover-tags: Discovers tags on the repository.
236 (default false)
237 :arg list head-pr-filter-behaviors: Definition of Filter Branch PR behaviors.
238 Requires the :jenkins-plugins:`SCM Filter Branch PR Plugin
239 <scm-filter-branch-pr>`. Refer to
240 :func:`~add_filter_branch_pr_behaviors <project_multibranch.add_filter_branch_pr_behaviors>`.
241 :arg dict notification-context: Change the default GitHub check notification
242 context from "continuous-integration/jenkins/SUFFIX" to a custom label / suffix.
243 (set a label and suffix to true or false, optional)
244 Requires the :jenkins-plugins:`Github Custom Notification Context SCM
245 Behaviour <github-scm-trait-notification-context>`.
246 Refer to :func:`~add_notification_context_trait <project_multibranch.add_notification_context_trait>`.
247 :arg dict property-strategies: Provides control over how to build a branch
248 (like to disable SCM triggering or to override the pipeline durability)
249 (optional)
250 Refer to :func:`~property_strategies <project_multibranch.property_strategies>`.
251 :arg bool exclude-archived-repositories: Whether archived repositories are
252 excluded when scanning an organization. (default: false) (optional)
253 :arg bool ssh-checkout: Checkout over SSH.
254
255 * **credentials** ('str'): Credentials to use for
256 checkout of the repo over ssh.
257
258 :extensions:
259
260 * **clean** (`dict`)
261 * **after** (`dict`) - Clean the workspace after checkout
262 * **remove-stale-nested-repos** (`bool`) - Deletes untracked
263 submodules and any other subdirectories which contain .git directories
264 (default false)
265 * **before** (`dict`) - Clean the workspace before checkout
266 * **remove-stale-nested-repos** (`bool`) - Deletes untracked
267 submodules and any other subdirectories which contain .git directories
268 (default false)
269 * **depth** (`int`) - Set shallow clone depth (default 1)
270 * **disable-pr-notifications** (`bool`) - Disable default github status
271 notifications on pull requests (default false) (Requires the
272 :jenkins-plugins:`GitHub Branch Source Plugin
273 <disable-github-multibranch-status>`.)
274 * **do-not-fetch-tags** (`bool`) - Perform a clone without tags
275 (default false)
276 * **lfs-pull** (`bool`) - Call git lfs pull after checkout
277 (default false)
278 * **prune** (`bool`) - Prune remote branches (default false)
279 * **refspecs** (`list(str)`): Which refspecs to fetch.
280 * **shallow-clone** (`bool`) - Perform shallow clone (default false)
281 * **sparse-checkout** (dict)
282 * **paths** (list) - List of paths to sparse checkout. (optional)
283 * **submodule** (`dict`)
284 * **disable** (`bool`) - By disabling support for submodules you
285 can still keep using basic git plugin functionality and just have
286 Jenkins to ignore submodules completely as if they didn't exist.
287 * **recursive** (`bool`) - Retrieve all submodules recursively
288 (uses '--recursive' option which requires git>=1.6.5)
289 * **tracking** (`bool`) - Retrieve the tip of the configured
290 branch in .gitmodules (Uses '\-\-remote' option which requires
291 git>=1.8.2)
292 * **parent-credentials** (`bool`) - Use credentials from default
293 remote of parent repository (default false).
294 * **reference-repo** (`str`) - Path of the reference repo to use
295 during clone (optional)
296 * **timeout** (`int`) - Specify a timeout (in minutes) for
297 submodules operations (default 10).
298 * **timeout** (`str`) - Timeout for git commands in minutes (optional)
299 * **use-author** (`bool`): Use author rather than committer in Jenkin's
300 build changeset (default false)
301 * **wipe-workspace** (`bool`) - Wipe out workspace before build
302 (default true)
303
304 Job examples:
305
306 .. literalinclude:: /../../tests/githuborg/fixtures/minimal.yaml
307
308 .. literalinclude:: /../../tests/githuborg/fixtures/github-org-full.yaml
309
310 """
311 github_path = "org.jenkinsci.plugins.github_branch_source"
312 github_path_dscore = "org.jenkinsci.plugins.github__branch__source"
313
314 mapping = [("repo-owner", "repoOwner", None)]
315 helpers.convert_mapping_to_xml(xml_parent, data, mapping, fail_required=True)
316
317 mapping_optional = [
318 ("api-uri", "apiUri", None),
319 ("credentials-id", "credentialsId", None),
320 ]
321 helpers.convert_mapping_to_xml(
322 xml_parent, data, mapping_optional, fail_required=False
323 )
324
325 traits = XML.SubElement(xml_parent, "traits")
326
327 # no-pr value is assumed if branch-discovery not mentioned.
328 if data.get("branch-discovery", "no-pr"):
329 bd = XML.SubElement(
330 traits, "".join([github_path_dscore, ".BranchDiscoveryTrait"])
331 )
332 bd_strategy = {"no-pr": "1", "only-pr": "2", "all": "3"}
333 bd_mapping = [("branch-discovery", "strategyId", "no-pr", bd_strategy)]
334 helpers.convert_mapping_to_xml(bd, data, bd_mapping, fail_required=True)
335
336 if data.get("ssh-checkout", None):
337 cossh = XML.SubElement(
338 traits, "".join([github_path_dscore, ".SSHCheckoutTrait"])
339 )
340 if not isinstance(data.get("ssh-checkout"), bool):
341 cossh_credentials = [("credentials", "credentialsId", "")]
342 helpers.convert_mapping_to_xml(
343 cossh, data.get("ssh-checkout"), cossh_credentials, fail_required=True
344 )
345
346 if data.get("discover-tags", False):
347 XML.SubElement(traits, "".join([github_path_dscore, ".TagDiscoveryTrait"]))
348
349 if data.get("discover-pr-forks-strategy", "merged-current"):
350 dprf = XML.SubElement(
351 traits, "".join([github_path_dscore, ".ForkPullRequestDiscoveryTrait"])
352 )
353 dprf_strategy = {"merge-current": "1", "current": "2", "both": "3"}
354 dprf_mapping = [
355 ("discover-pr-forks-strategy", "strategyId", "merge-current", dprf_strategy)
356 ]
357 helpers.convert_mapping_to_xml(dprf, data, dprf_mapping, fail_required=True)
358
359 trust = data.get("discover-pr-forks-trust", "contributors")
360 trust_map = {
361 "contributors": "".join(
362 [github_path, ".ForkPullRequestDiscoveryTrait$TrustContributors"]
363 ),
364 "everyone": "".join(
365 [github_path, ".ForkPullRequestDiscoveryTrait$TrustEveryone"]
366 ),
367 "permission": "".join(
368 [github_path, ".ForkPullRequestDiscoveryTrait$TrustPermission"]
369 ),
370 "nobody": "".join(
371 [github_path, ".ForkPullRequestDiscoveryTrait$TrustNobody"]
372 ),
373 }
374 if trust not in trust_map:
375 raise InvalidAttributeError(
376 "discover-pr-forks-trust", trust, trust_map.keys()
377 )
378 XML.SubElement(dprf, "trust").attrib["class"] = trust_map[trust]
379
380 dpro_strategy = data.get("discover-pr-origin", "merge-current")
381 if dpro_strategy:
382 dpro = XML.SubElement(
383 traits, "".join([github_path_dscore, ".OriginPullRequestDiscoveryTrait"])
384 )
385 dpro_strategy_map = {"merge-current": "1", "current": "2", "both": "3"}
386 if dpro_strategy not in dpro_strategy_map:
387 raise InvalidAttributeError(
388 "discover-pr-origin", dpro_strategy, dpro_strategy_map.keys()
389 )
390 dpro_mapping = [
391 ("discover-pr-origin", "strategyId", "merge-current", dpro_strategy_map)
392 ]
393 helpers.convert_mapping_to_xml(dpro, data, dpro_mapping, fail_required=True)
394
395 if data.get("head-filter-regex", None):
396 rshf = XML.SubElement(traits, "jenkins.scm.impl.trait.RegexSCMHeadFilterTrait")
397 XML.SubElement(rshf, "regex").text = data.get("head-filter-regex")
398
399 if data.get("repo-name-regex", None):
400 rssf = XML.SubElement(
401 traits,
402 "jenkins.scm.impl.trait.RegexSCMSourceFilterTrait",
403 {"plugin": "scm-api"},
404 )
405 XML.SubElement(rssf, "regex").text = data.get("repo-name-regex")
406
407 if data.get("head-pr-filter-behaviors", None):
408 multibranch.add_filter_branch_pr_behaviors(
409 traits, data.get("head-pr-filter-behaviors")
410 )
411
412 if data.get("property-strategies", None):
413 multibranch.property_strategies(xml_parent, data)
414
415 multibranch.add_notification_context_trait(traits, data)
416
417 # handle the default git extensions like:
418 # - clean
419 # - shallow-clone
420 # - timeout
421 # - do-not-fetch-tags
422 # - submodule
423 # - prune
424 # - wipe-workspace
425 # - use-author
426 # - lfs-pull
427 git_extensions(traits, data)
428
429 if data.get("refspecs"):
430 refspec_trait = XML.SubElement(
431 traits,
432 "jenkins.plugins.git.traits.RefSpecsSCMSourceTrait",
433 {"plugin": "git"},
434 )
435 templates = XML.SubElement(refspec_trait, "templates")
436 refspecs = data.get("refspecs")
437 for refspec in refspecs:
438 e = XML.SubElement(
439 templates,
440 (
441 "jenkins.plugins.git.traits"
442 ".RefSpecsSCMSourceTrait_-RefSpecTemplate"
443 ),
444 )
445 XML.SubElement(e, "value").text = refspec
446
447 # github-only extensions
448 disable_github_status_path_dscore = (
449 "com.adobe.jenkins.disable__github__multibranch__status"
450 )
451 if data.get("disable-pr-notifications", False):
452 XML.SubElement(
453 traits,
454 "".join([disable_github_status_path_dscore, ".DisableStatusUpdateTrait"]),
455 {"plugin": "disable-github-multibranch-status"},
456 )
457
458 if data.get("exclude-archived-repositories", False):
459 XML.SubElement(
460 traits,
461 "".join([github_path_dscore, ".ExcludeArchivedRepositoriesTrait"]),
462 )