Skip to Content

Wiki source code of Jenkins Shared Library

Version 9.3 by Boris Folgmann on 2025/11/03 09:20
Show last authors
1 {{toc/}}
2
3 = DevOps-as-a-Service Open Source Pipeline Library =
4
5 DevOps-as-a-Service provides a standardized Jenkins Shared Library to be used for all your builds. See [[https:~~/~~/prd.sdc.t-systems.net/bitbucket/projects/DEVOPSAAS/repos/sdcloud-caas-jenkins-libs/browse>>url:https://prd.sdc.t-systems.net/bitbucket/projects/DEVOPSAAS/repos/sdcloud-caas-jenkins-libs/browse||shape="rect"]] for the source code and additional documentation like e.g. release notes.
6
7 == Getting Started ==
8
9 Since the Shared Library is globally configured on all Jenkins instances managed by DevOps-as-a-Service you just need to place the following very short Jenkinsfile in the root folder of your git repository to automatically build your maven, node or go project or simply build a container using a Dockerfile.
10
11 {{code}}
12 @Library('sdcloud') _
13
14 sdcPipeline()
15 {{/code}}
16
17 Calling sdcPipeline() starts an automatically configured, standardized build and deployment pipeline.
18 The pipeline requires a node labeled with 'docker' to execute successfully. To run on other types of Jenkins agents set the //useNode //argument as described below.
19
20 == Pipeline features ==
21
22 What the pipeline currently does is visualised in the following image which shows an example for a maven-based Java project.
23
24 [[image:1762161531690-966.png||data-xwiki-image-style-border="true" height="247" width="1654"]]
25
26 1. sdcPipeline prints some valuable information about this shared Jenkinslib. Allocates a node (Jenkins Agent) to start executing
27 1. Checking out the source code from git.
28 1. If a pom.xml is found your favorite JDK is selected, by default jdk11. Then a maven build is done.
29 1. If there's no pom.xml but a package.json is found a nodejs build is done.
30 1. If there is no pom.xml or package.json but a go.mod file, a go build is done.
31 1. Then the following stages are executed in parallel
32 11. Analysis: For maven projects the Java source code is checked by checkstyle, pmd and spotbugs. Furthermore the job output will be checked for any warnings generated by maven, javac or javadoc. If Python modules (.py files) exist in the git repository they will be analyzed using pylint and flake8. If pylint or flake8 are not available on the Jenkins agent the steps will be skipped. Python files that are generated or downloaded into the workspace will not be checked. The results will be displayed on the classical Jenkins build page after the build. For Go projects, the Go test tool is used to run all tests and produce a coverage output file for SonarQube. Additionally, the gotestsum tool is used to produce a report which is picked up by Jenkins.</dd>
33 11. Security: If it's not a feature or bugfix branch a dependency check is done which checks if e.g. libraries are used which have known vulnerabilities. The results will be displayed in Jenkins after the build.
34 11. Docker: this will also work for projects which are neither maven or nodejs. A Dockerfile is enough to trigger this part of the pipeline.
35 111. If a Dockerfile is found a docker image is built.
36 111. The image is started as an isolated container on the Jenkins agent.
37 111. Any loglines written to stdout or stderr by the container will be displayed.
38 111. A smoke test is performed which is a simple query for a valid answer on the exposed port of the container.
39 111. If the smoke test was successful and the build was not done for a pull request the docker image will be pushed to the docker registry.
40 111. For easy identification of the image 3 image tags are defined:
41 1111. BRANCH_NAME-BUILD_NUMBER (e.g. 'production-1014')
42 1111. BRANCH_NAME-GIT_HASH (e.g. 'develop-8a7c4f2')
43 1111. BRANCH_NAME-latest (e.g. 'feature-PKEY-42-latest')
44 1111. (If BRANCH_NAME is defaultBranch the prefix 'BRANCH_NAME-' will not be included.)
45 111. When a chart/Chart.yaml is found and  it's not a pull request a Helm Chart will be created and pushed to the Helm Chart repository.
46 1. Yamllint will check all YAML files in the workspace for errors and warnings. This is done at this place since the Create Helm Chart stage modifies or creates YAML files which should be also checked before the pipeline proceeds.
47 1. When depolyHelmChart is set to true the Helm chart will be deployed to the Kubernestes cluster and namespace of your choice. Not done in the example diagram.
48
49 == {{id name="pipeline_customization"/}}Pipeline Customization ==
50
51 By passing named arguments to sdcPipline() e.g. sdcPipeline(imageName: 'nginx-demo', imageTag: 'v1.4') you can change the default configuration of the pipeline.
52
53 (% class="table-bordered" style="width:100.0%" %)
54 (% class="active" %)|=(((
55 Category
56 )))|=(((
57 Argument
58 )))|=(((
59 Default
60 )))|=(((
61 Description
62 )))
63 |=(% rowspan="4" %)(((
64 Job execution
65 )))|(((
66 decorateOutput
67 )))|(((
68 true
69 )))|(((
70 Enables timestamps and colorization for the console output when set to true.
71 )))
72 |allocateNode|true|(((
73 Specifies if a node should be allocated for executing the sdcPipeline code.
74
75 If you set this to false you will need to put your sdcPipeline() call into a node {} block.
76 )))
77 |(((
78 useNode
79 )))|(((
80 'docker'
81 )))|(((
82 Specifies which node should be allocated and used by the pipeline if allocateNode is true.
83
84 Pass a label or name of a configured Jenkins agent.
85 )))
86 |(((
87 defaultBranch
88 )))|(((
89 'master'
90 )))|(((
91 This branch will be the integration branch for work. At some points the pipeline will behave differently, if the default branch or another branch ist currently being built.
92 )))
93 |=(% rowspan="5" %)(((
94 Programming language and build tool
95 )))|(((
96 jdk
97 )))|(((
98 'jdk11'
99 )))|(((
100 JDK to use for all Java operations. Refers to a symbolic name of a Java tool configuration in Jenkins.
101 )))
102 |(((
103 mvnCommand
104 )))|(((
105 'mvn clean verify'
106 )))|(((
107 maven command to execute for building maven projects.
108 )))
109 |(((
110 mavenSettingsConfig
111 )))|(((
112 ''
113 )))|(((
114 Select a maven settings element from File Config Provider. The settings element in the settings.xml file contains elements used to define values which configure Maven execution in various ways, like the pom.xml, but should not be bundled to any specific project, or distributed to an audience. These include values such as the local repository location, alternate remote repository servers, and authentication information.
115
116 See also [[doc:Jenkins.Using Maven Artifact Repositories in Jenkins.WebHome]].
117 )))
118 |(((
119 nodejs
120 )))|(((
121 'nodejs'
122 )))|(((
123 Node.js to use for all node operations like e.g. calling npm. Refers to a symbolic name of a nodejs tool configuration in Jenkins.
124 )))
125 |(((
126 npmCommand
127 )))|(((
128 'npm install && npm run build ~-~-prod'
129 )))|(((
130 npm command to execute for building Node.JS projects.
131 )))
132 |= |go|'go'|Golang version to use.
133 Refers to a symbolic name of a go tool configuration in Jenkins.
134 |= |goBuildCommand|(((
135 'go build -o app cmd/server/main.go'
136 )))|go build run. Should be overridden for your project.
137 |= |goTestCommand|'gotestsum ~-~-format pkgname ~-~-junitfile report.xml ~-~- -failfast -race -coverprofile=coverage.out -tags=test ./...'|Runs gotestsum tool which in turn calls 'go test' for all packages in the project. Should be overridden for your project. The gotestsum tool is available out-of-the-box and produces a report file which is picked up by Jenkins automatically.
138 |=(% rowspan="10" %)(((
139 Docker build
140 )))|(((
141 dockerBuildPath
142 )))|(((
143 '.' (current directory)
144 )))|(((
145 Path to use for building the Docker container.
146 )))
147 |(((
148 dockerBuildArgs
149 )))|(((
150 '' (empty string)
151 )))|(((
152 Any additional arguments for Docker build.
153 )))
154 |(((
155 dockerfile
156 )))|(((
157 dockerBuildPath/Dockerfile
158 )))|(((
159 Dockerfile to use for building the Docker container.
160 )))
161 |(((
162 imageName
163 )))|(((
164 artifactId from pom.xml for maven projects
165
166 name of the build job for all other project types
167 )))|(((
168 Name to be used for the built Docker image.
169 )))
170 |(((
171 imagePath
172 )))|(((
173 Name of the project folder in Jenkins. That's the PROJECTKEY from the self-service portal
174 )))|(((
175 Path to prepend before the imageName.
176 )))
177 |(((
178 imageTag
179 )))|(((
180 nothing
181 )))|(((
182 Additional tag to set on the container. It will be automatically prefixed with the branch name, except for the defaultBranch.
183 )))
184 |(((
185 gitHashLength
186 )))|(((
187 7
188 )))|(((
189 Number of digits from the git hash that will be used as an image tag on the container image to label the build.
190 )))
191 |(((
192 gitCredentialsId
193 )))|(((
194 'PROJECTKEY-git' (credential which was added to your project folder in Jenkins when the project was set up by the self-service portal)
195 )))|(((
196 Name of credentials used to connect to Bitbucket API. May be used to connect to alternative SCM tools in the future.
197 )))
198 |(((
199 pullDockerRegistry
200 )))|(((
201 '[[https:~~/~~/registry-CUSTOMER.devops.t-systems.net>>url:https://registry-CUSTOMER.devops.t-systems.net||shape="rect"]]' (docker registry of your DOaaS instance)
202 )))|(((
203 If you need to pull base images during the Docker build from a docker registry that requires authentication you have to use this to specify it.
204 )))
205 |(((
206 pullDockerRegistryCredentialsId
207 )))|(((
208 'doaas-PROJECTKEY+jenkins-push-harbor' or 'PROJECTKEY-jenkins' (which were added to the credentials of your project folder in Jenkins when the project was set up by the DevOps Portal. While the first is added for Harbor, the second is added for Nexus OSS. That means that the library will automatically choose the best default for you. Please note that Harbor will be prefered, if both tools are used in the project.)
209 )))|(((
210 Id of the Jenkins Credentials which have to be used to authenticate to the //pullDockerRegistry//.
211 )))
212 |=(% rowspan="7" %)(((
213 Docker container test
214 )))|(((
215 skipSmokeTest
216 )))|(((
217 false
218 )))|(((
219 Set to true to skip the container smoke test after the build.
220 )))
221 |(((
222 containerArgs
223 )))|(((
224 '' (empty string)
225 )))|(((
226 Arguments to pass to the container for the smoke test.
227 )))
228 |(((
229 containerPort
230 )))|(((
231 80
232 )))|(((
233 Exposed port of the container that is used to check for an answer during the smoke test.
234 )))
235 |(((
236 containerProtocol
237 )))|(((
238 'http'
239 )))|(((
240 Protocol to use when trying to connect to the port of the container. Possible values: 'http', 'tcp', 'udp'. 'http' will be tested with curl, 'tcp' and 'udp' will be tested with ncat.
241 )))
242 |(((
243 containerContextPath
244 )))|(((
245 '' (empty string)
246 )))|(((
247 contextPath to query for the smoke test if the container protocol is 'http'
248 )))
249 |(((
250 containerMaxLoglineTime
251 )))|(((
252 15
253 )))|(((
254 After starting the container the smoke tests monitors stdout of the container for loglines. After containerMaxLoglineTime which is specified in seconds have passed without a new logline found, the container is expected to be up and running and the test query is performed. Increase if your container doesn't write loglines that often and seems to be not ready when the test query is performed.
255 )))
256 |(((
257 containerMaxStartupTime
258 )))|(((
259 180 (3 minutes)
260 )))|(((
261 Total time in seconds after which the container is expected to be up and running even if it's still writing loglines to stdout. After this time has passed the container will be queried for an answer.
262 )))
263 |=(% rowspan="2" %)(((
264 Docker push
265 )))|(((
266 pushDockerRegistry
267 )))|(((
268 '[[https:~~/~~/registry-CUSTOMER.devops.t-systems.net>>url:https://registry-CUSTOMER.devops.t-systems.net||shape="rect"]]' (docker registry of your DOaaS instance)
269 )))|(((
270 Docker registry to which the built image will be pushed after a successful smoke test.
271 )))
272 |(((
273 pushDockerRegistryCredentialsId
274 )))|(((
275 'doaas-PROJECTKEY+jenkins-push-harbor' or 'PROJECTKEY-jenkins' (which were added to the credentials of your project folder in Jenkins when the project was set up by the DevOps Portal. While the first is added for Harbor, the second is added for Nexus OSS. That means that the library will automatically choose the best default for you. Please note that Harbor will be prefered, if both tools are used in the project.)
276 )))|(((
277 Id of the Jenkins Credentials which have to be used to authenticate to the //pullDockerRegistry//.
278 )))
279 |=(% rowspan="6" %)(((
280 Helm chart
281 )))|(((
282 helmChartPath
283 )))|(((
284 './chart'
285 )))|(((
286 Specifies the path to the YAML files for the helm command.
287 )))
288 |(((
289 appName
290 )))|(((
291 artifactId from pom.xml for maven projects
292
293 name of the build job for all other project types
294 )))|(((
295 Name of the application. Used to build the name of the Helm chart.
296 )))
297 |(((
298 appVersion
299 )))|(((
300 version from pom.xml for maven projects
301
302 '1.0.0' for all other project types
303 )))|(((
304 Version of the application. Used to set the app version of the Helm chart.
305 )))
306 |(((
307 chartVersion
308 )))|(((
309 appVersion with '00' appended
310 )))|(((
311 Version of the Helm chart. Used to set the chart version of the Helm chart.
312 )))
313 |(((
314 helmRegistry
315 )))|(((
316 Helm registry of your DOaaS instance, which is usally 'https:~/~/registry-CUSTOMER.devops.t-systems.net/chartrepo/PROJECTKEY'
317 )))|(((
318 Helm registry to which the packaged Helm chart is uploaded.
319
320
321 )))
322 |(((
323 helmRegistryCredentialsId
324 )))|(((
325 'doaas-PROJECTKEY+jenkins-push-harbor' or 'PROJECTKEY-jenkins' (which were added to the credentials of your project folder in Jenkins when the project was set up by the DevOps Portal. While the first is added for Harbor, the second is added for Nexus OSS. That means that the library will automatically choose the best default for you. Please note that Harbor will be prefered, if both tools are used in the project.)
326 )))|(((
327 Id of the Jenkins Credentials which have to be used to authenticate to the Helm registry for acccessing Helm charts.
328 )))
329 |=(% rowspan="4" %)(((
330 Container image signature
331 )))|(((
332 signImages
333 )))|(((
334 false
335 )))|(((
336 When set to true, it activates signing of generated Docker images.
337 )))
338 |(((
339 signingNotaryServer
340 )))|(((
341 '[[https:~~/~~/notary.external.otc.telekomcloud.com>>url:https://notary.external.otc.telekomcloud.com||shape="rect"]]' (Magenta Trusted Registry)
342 )))|(((
343 Specifies the Notary service to be used for signing.
344 )))
345 |(((
346 signingPassphraseCredentialsId
347 )))|(((
348 'docker-trust-PROJECTKEY-passphrase'
349 )))|(((
350 Id of the Jenkins Credentials for passphrase of signers keyfile.
351 )))
352 |(((
353 signingKeyfileCredentialsId
354 )))|(((
355 'docker-trust-PROJECTKEY-keyfile'
356 )))|(((
357 Id of the Jenkins Credentials for signers private keyfile.
358 )))
359 |=(% colspan="1" rowspan="8" %)(((
360 Static Source Code Analysis
361 )))|(((
362 checkstyleConfig
363 )))|(((
364 best-practice releaxed configuration
365 )))|(((
366 Name of a config file to use for checkstyle. If not set a best-practice[[ relaxed configuration >>url:https://prd.sdc.t-systems.net/bitbucket/projects/DEVOPSAAS/repos/sdcloud-caas-jenkins-libs/browse/resources/com/tsystems/sdc/jenkinslib/checkstyle.xml||shape="rect"]]is used which is different from the original  Sun[[ Java Style>>url:https://checkstyle.org/sun_style.html||shape="rect"]].
367 To get the old behavior simply specify 'sun_checks.xml' to get the original Sun Checks. As an alternative 'google_checks.xml' can be used for the Google Checks which is another ruleset predefined in the checkstyle scanner tool.
368 For a custom configuration specify a filesystem path, a URL, or a classpath resource. This parameter expects that the contents of the location conforms to the xml format (Checkstyle Checker module) configuration of rulesets.
369 )))
370 |(((
371 skipBlames
372 )))|(((
373 false
374 )))|(((
375 If set to true all recordIssues steps will skip creating the SCM blames. This speeds up the processing of the results of static source code analyis. As a consequence you will not be able to see who introduced a problem into the code.
376 )))
377 |(((
378 yamlConfig
379 )))|(((
380 best-practice releaxed configuration
381 )))|(((
382 Name of a config file to use for yamllint. If not set a best-practice[[ relaxed configuration >>url:https://prd.sdc.t-systems.net/bitbucket/projects/DEVOPSAAS/repos/sdcloud-caas-jenkins-libs/browse/resources/com/tsystems/sdc/jenkinslib/yamllint.yml||shape="rect"]]is used which is different from the original yamllint[[ config>>url:https://yamllint.readthedocs.io/en/stable/configuration.html#default-configuration||shape="rect"]].
383 )))
384 |(((
385 sonarQube
386 )))|(((
387 true for the defaultBranch and for pull-requests, if a SonarQube version is detected which supports scanning multiple branches
388
389 false for all other branches
390 )))|(((
391 Set this to true to force a SonarQube scan for the current branch. Usually this makes only sense if you explicitly want to scan feature and bugfix branches.
392
393 If not set or set to false, the default branch will be scanned automatically as well as pull-requests, if a SonarQube version is detected which supports scanning multiple branches. This is currently the case for SonarQube Developer and Enterprise editions. The free SonarQube Community edition supports just one branch.
394 )))
395 |(((
396 sonarScanMavenOpts
397 )))|(((
398 ''
399 )))|(((
400 For huge source codes it can happen that the sonar scanner aborts with java.lang.OutOfMemoryError. In this case the memory that is availalbe for the sonar scanner needs to be increased. Try something like '-Xmx512m' to set a larger heap space for the JVM that is executing the maven-based sonar scan. '-Xmx3g' should be enough for most source codes, but make sure that your Jenkins agent has enough memory to cope with that.
401 )))
402 |sonarScanOpts|''|For huge source codes it can happen that the sonar scanner aborts with java.lang.OutOfMemoryError. In this case the memory that is availalbe for the sonar scanner needs to be increased. Try something like '-Xmx512m' to set a larger heap space for the JVM that is executing the
403 sonar scan. '-Xmx3g' should be enough for most source codes, but make sure that your Jenkins agent has enough memory to cope with that.
404 |(((
405 sonarSources
406 )))|(((
407 'src/main' for maven projects
408
409 null for non-maven projects
410 )))|(((
411 (% class="content-wrapper" %)
412 (((
413 Comma-separated paths to directories containing main source files to scan with SonarQube. Defaults to 'src/main' and therefore will automatically discover folders like src/main/java, src/main/webapp or src/main/resources. This makes sure to not only scan Java sources, but also for example JSP, CSS and HTML files.
414
415 Sonar scanning will fail if the configured directory itself is not found at all. This can happen if you have defined an alternative <sourceDirectory> in your pom.xml. If this is the case, you can disable sonar scanning by adding
416
417 {{code language="xml"}}
418 <properties>
419 <sonar.skip>true</sonar.skip>
420 </properties>
421 {{/code}}
422
423 to the pom.xml. If this is not what you want, set sonarSources to {{code language="none"}}null{{/code}}. This will make sure that sonar.sources are not explicitly passed to the sonar scanner. This will allow you to specify sonar.sources in the pom.xml like in the following example:
424
425 {{code language="xml"}}
426 <properties>
427 <sonar.source>src/main/java,src/main/webapp</sonar.sources>
428 </properties>
429 {{/code}}
430 )))
431 )))
432 |sonarQualityGate| |Sets the desired quality gate to use for the scan result in SonarQube.
433 If not specified, the quality gate is not changed.
434 As a default, SonarQube will use the quality gate "Sonar way" for new scan results.
435 |=(% colspan="1" rowspan="5" %)Dependency Check|skipDependencyCheck|false|Set to true to skip the dependency-check.
436 |dependencyCheckTool|'dependency-check'|Defines which named dependency-check tool should be used.
437 |dependencyCheckMvnArgs|'-DassemblyAnalyzerEnabled=false'|Additional arguments which are be passed to dependency-check for maven projects.(((
438 See [[Dependency Check Maven Configuration>>https://jeremylong.github.io/DependencyCheck/dependency-check-maven/configuration.html]] for more information.
439 )))
440 |dependencyCheckArgs|'~-~-disableAssembly'|Addtional arguments which are be passed to dependency-check. See [[Dependency>>url:https://jeremylong.github.io/DependencyCheck/dependency-check-cli/arguments.html||shape="rect"]][[ Check CLI Arguments>>url:https://jeremylong.github.io/DependencyCheck/dependency-check-cli/arguments.html||shape="rect"]] for more information.
441 |dependencyCheckNvdApiKeyCredentialsId|'dependency-check-nvdapikey'|If you have your own NVD API Key, set it as a credential of type text in Jenkins. Then specify the credential id using this argument. It will be automatically passed to dependency-check. There will be no error if no credential is found. Just the NVD download will be slower. Please note, on DevOps-as-a-Service a shared NVD API Key is automatically supplied for the default credential id.
442 |=(% colspan="1" rowspan="2" %)Dependency Track|depTrackCredentialsId|'PROJECTKEY-deptrack-projectcreator'|(((
443 Id of the Jenkins Credential which has to be used to authenticate to Dependency Track for publishing the SBOM.
444 )))
445 |depTrackClassifier|'application'|The component type (e.g. application, library, firmware, ...) that should be set in the SBOM file.
446 Will be later shown as classifier for the project in Dependency Track.
447 See [[CycloneDX Metadata Component Type>>https://cyclonedx.org/docs/1.6/json/#metadata_component_type]] for supported values.
448 |=(% colspan="1" rowspan="2" %)Trivy|trivySeverity|'High'|String which sets the minimum severity of Trivy findings that has to be reached to mark the Trivy Results stage as unstable.
449 Possible values are: "None", "Unknown", "Negligible", "Low", "Medium", "High", "Critical".
450 |trivyBuildResult|'SUCCESS'|String which sets the overall build result when the result of the Trivy scan reaches trivyServerity.
451 Possible values are: "SUCCESS", "UNSTABLE" or "FAILURE"
452 |=(% rowspan="7" %)(((
453 Deployment
454 )))|(((
455 deployHelmChart
456 )))|(((
457 false
458 )))|(((
459 Boolean that activates or deactivates the automatic deployment of the Helm-Chart.
460 )))
461 |(((
462 kubeconfigCredentialsId
463 )))|(((
464 'kubeconfig-deployer-PROJECTKEY'
465 )))|(((
466 Id of the Jenkins credential which contains the kubeconfig file that should be used for deployment. The file is required to authorize access to the Kubernetes cluster.
467 )))
468 |(((
469 kubernetesNamespace
470 )))|(((
471 'default'
472 )))|(((
473 Name of the namespace in Kubernetes, to which the Chart will be deployed.
474 )))
475 |(((
476 helmValuesOverrideFile
477 )))|(((
478 'chart/values.yaml'
479 )))|(((
480 Name of the YAML file which contains specific values that should be overridden for the automatic deployment. The location needs to be specified relative to the Jenkinsfile.
481 )))
482 |(((
483 helmSetValues
484 )))|(((
485 ''
486 )))|(((
487 Set values using the format "key1=val1,key2=val2,..." for the automatic deployment.
488
489 While helmValuesOverrideFile is usally something static you can use this to specify different values depending on e.g. conditions in your Jenkinsfile.
490
491 Will be ignored if set to null, empty string or just white space.
492 )))
493 |(((
494 helmReleaseName
495 )))|(((
496 artifactId from pom.xml for maven projects
497
498 name of the build job for all other project types
499 )))|(((
500 Name of the Helm Release which will be installed or upgraded in your cluster.
501 )))
502 |(((
503 helmLockResource
504 )))|(((
505 null
506 )))|(((
507 Using [[lock>>url:https://www.jenkins.io/doc/pipeline/steps/lockable-resources/#lock-lock-shared-resource||shape="rect"]] the specified resource will be locked for the execution of any
508
509 (% class="code" %)
510 (((
511 helm upgrade
512 )))
513
514 or
515
516 (% class="code" %)
517 (((
518 helm uninstall
519 )))
520
521 command. This makes sense if deployHelmChart is used to upgrade an deployment in an environment which is currently used, e.g. for automated testing. In this case wrap your test in a lock statement with the same resource name. Defaults to null, which will not lock any resource.
522 )))
© 2018-2025 T-Systems International GmbH