Jenkinsfile - XWiki

This page describes, how to do things in scripted Pipeline (Groovy) Jenkinsfiles. This [[link >>url:https://www.jenkins.io/doc/book/pipeline/jenkinsfile/||shape="rect"]]is a good starting point to learn more about Jenkinsfile.

2

3

= General =

The Jenkinsfile must be located in the root folder of a repository / branch, to be detected by Jenkins automatically. The Jenkinsfile defines, how the build job is performed by Jenkins.

= Properties =

At the top of the Jenkinsfile properties can be called with an array of global properties that will be set for the pipeline.

properties([

... , ... , ...

])

Please note that another call to {{code language="none"}}properties(){{/code}} will overwrite the previous one!

21

22

== Build Discarder ==

23

24

At the top of the Jenkinsfile add a buildDiscarder to the properties to let Jenkins delete old artifacts or complete job executions:

25

26

{{code language="groovy" title="ℹ **Example**

27

"}}

28

properties([

29

buildDiscarder(logRotator(numToKeepStr: '50', artifactNumToKeepStr: '5'))

])

Parameters for {{code language="none"}}logRotator{{/code}} (from [[the source code>>url:https://github.com/jenkinsci/jenkins/blob/master/core/src/main/java/hudson/tasks/LogRotator.java#L53||shape="rect"]]):

34

35

* {{code language="none"}}daysToKeepStr{{/code}}: history is only kept up to this days.

36

* {{code language="none"}}numToKeepStr{{/code}}: only this number of build logs are kept.

37

* {{code language="none"}}artifactDaysToKeepStr{{/code}}: artifacts are only kept up to this days.

38

* {{code language="none"}}artifactNumToKeepStr{{/code}}: only this number of builds have their artifacts kept.

39

40

== Pipeline Triggers ==

41

42

Instead of having pipelines just triggered on source code changes you can also use cron syntax to define dates and times that shoud automatically trigger the pipeline.

43

44

{{code language="groovy" title="**ℹ Example**

45

"}}

46

properties([

47

pipelineTriggers([cron('TZ=Europe/Berlin \n 00 08 * * 1-5')])

])

The above example triggers the pipeline at 8:00 on Mo-Fr using the local German time. Without the TZ specification it will use the timezone of the Jenkins server which is UTC for DevOps-as-a-Service.

52

53

More about the cron spec is documented at [[https:~~/~~/jenkins.io/doc/book/pipeline/syntax/#cron-syntax>>url:https://jenkins.io/doc/book/pipeline/syntax/#cron-syntax||shape="rect"]].

54

55

== Durability Settings ==

56

57

At the top of the Jenkinsfile add a durabilityHint to the properties:

58

59

{{code language="groovy" title="**ℹ Example**

60

"}}

61

properties([

62

durabilityHint('PERFORMANCE_OPTIMIZED')

])

The possible values and their meaning are documented at: [[https:~~/~~/jenkins.io/doc/book/pipeline/scaling-pipeline/>>url:https://jenkins.io/doc/book/pipeline/scaling-pipeline/||shape="rect"]]

67

68

If unsure, please don't change the default!

69

70

= Automated building =

71

72

The best and easiest approach to use the power of Jenkins pipelines is to use the automatically provided [[doc:Jenkins.Jenkins Shared Library.WebHome]] which will detect the type of your project and automatically build and test it. The pipeline also provides optional deployments to target environments. See [[doc:Jenkins.Jenkins Shared Library.WebHome]] for more information!

73

74

= Building with tool plug-ins =

75

76

Some build tools have a special plug-in support in Jenkins which means you can easily call them on any Jenkins node. Jenkins will make sure to install and update them for you. In your Jenkinsfile you just refer with symbolic names to the major version of the tool you want to use. The DevOps-as-a-Service team will make sure that the latest Long Term Support (LTS) version of the tool will be automatically available for you. Most of the time these updates are done together with the update of your Jenkins controller instance.

77

78

We strive to make the exact version of the different tools publicly available on the start page of your Jenkins. See the screenshot below as an example. Put please check the current versions available to you at [[https:~~/~~/CUSTOMER.devops.t-systems.net/jenkins/>>url:https://CUSTOMER.devops.t-systems.net/jenkins/||shape="rect"]] where CUSTOMER needs to be replaced by the name of your instance.

79

80

[[image:attach:image2022-11-10_10-27-6.png||data-xwiki-image-style-border="true" queryparams="effects=drop-shadow" height="250"]]

== Maven ==

Supported symbolic name is 'maven'. The exact version can be looked up at the start page of your Jenkins, e.g. [[https:~~/~~/CUSTOMER.devops.t-systems.net/jenkins/>>url:https://CUSTOMER.devops.t-systems.net/jenkins/||shape="rect"]]

85

86

{{code language="groovy" title="ℹ **Scripted Pipeline**

87

"}}

88

withMaven(maven: 'maven')

{

sh 'mvn --version'

}

For more information about the withMaven pipeline step see [[https:~~/~~/www.jenkins.io/doc/pipeline/steps/pipeline-maven/>>url:https://www.jenkins.io/doc/pipeline/steps/pipeline-maven/||shape="rect"]]. When you use the [[doc:Jenkins.Jenkins Shared Library.WebHome]] a maven build will be automatically done when a pom.xml file is found.

95

96

== JDK (Java Development Kit) ==

97

98

The supported symbolic names are listed at the start page of your Jenkins (e.g. [[https:~~/~~/CUSTOMER.devops.t-systems.net/jenkins/>>url:https://CUSTOMER.devops.t-systems.net/jenkins/||shape="rect"]]) and start with 'jdk' or 'corretto'.

99

100

The following examples use jdk17.

101

102

{{code language="groovy" title="**ℹ Scripted Pipeline**

103

"}}

104

env.JAVA_HOME = "${tool 'jdk17'}"

105

env.PATH="${env.JAVA_HOME}/bin:${env.PATH}"

sh 'java -version'

When you use the [[doc:Jenkins.Jenkins Shared Library.WebHome]] you simply do

110

111

{{code language="groovy" title="**ℹ Scripted Pipeline**

112

"}}

113

@Library('sdcloud') _

114

115

sdcPipeline(jdk: 'jdk17')

116

117

118

to use the JDK version of your choice. See [[doc:Jenkins.Jenkins Shared Library.WebHome||anchor="PipelineCustomization"]] for more information.

== nodejs ==

The supported symbolic names are listed at the start page of your Jenkins (e.g. [[https:~~/~~/CUSTOMER.devops.t-systems.net/jenkins/>>url:https://CUSTOMER.devops.t-systems.net/jenkins/||shape="rect"]]) and start with 'nodejs'. As an example 'nodes16' would be refering to the latest release of nodejs v16. The short name 'nodejs' is usually set to the recommended LTS version of nodejs.

123

124

The following examples use 'nodejs18'.

125

126

{{code language="groovy" title="**ℹ Scripted Pipeline**

127

"}}

128

env.NODEJS_HOME = "${tool 'nodejs18'}"

129

env.PATH="${env.NODEJS_HOME}/bin:${env.PATH}"

sh 'node --version'

sh 'npm --version'

When you use the [[doc:Jenkins.Jenkins Shared Library.WebHome]] you simply do

135

136

{{code language="groovy" title="**ℹ Scripted Pipeline**

137

"}}

138

@Library('sdcloud') _

139

140

sdcPipeline(nodejs: 'nodejs18')

141

142

143

to use the nodejs version of your choice. See [[doc:Jenkins.Jenkins Shared Library.WebHome||anchor="PipelineCustomization"]] for more information.

version	line-number	content
1.1	1	This page describes, how to do things in scripted Pipeline (Groovy) Jenkinsfiles. This [[link >>url:https://www.jenkins.io/doc/book/pipeline/jenkinsfile/\|\|shape="rect"]]is a good starting point to learn more about Jenkinsfile.
	2
	3
	4	{{toc/}}
	5
	6	= General =
	7
	8	The Jenkinsfile must be located in the root folder of a repository / branch, to be detected by Jenkins automatically. The Jenkinsfile defines, how the build job is performed by Jenkins.
	9
	10	= Properties =
	11
	12	At the top of the Jenkinsfile properties can be called with an array of global properties that will be set for the pipeline.
	13
	14	{{code language="groovy"}}
	15	properties([
	16	... , ... , ...
	17	])
	18	{{/code}}
	19
	20	Please note that another call to {{code language="none"}}properties(){{/code}} will overwrite the previous one!
	21
	22	== Build Discarder ==
	23
	24	At the top of the Jenkinsfile add a buildDiscarder to the properties to let Jenkins delete old artifacts or complete job executions:
	25
	26	{{code language="groovy" title="ℹ Example
	27	"}}
	28	properties([
	29	buildDiscarder(logRotator(numToKeepStr: '50', artifactNumToKeepStr: '5'))
	30	])
	31	{{/code}}
	32
	33	Parameters for {{code language="none"}}logRotator{{/code}} (from [[the source code>>url:https://github.com/jenkinsci/jenkins/blob/master/core/src/main/java/hudson/tasks/LogRotator.java#L53\|\|shape="rect"]]):
	34
	35	* {{code language="none"}}daysToKeepStr{{/code}}: history is only kept up to this days.
	36	* {{code language="none"}}numToKeepStr{{/code}}: only this number of build logs are kept.
	37	* {{code language="none"}}artifactDaysToKeepStr{{/code}}: artifacts are only kept up to this days.
	38	* {{code language="none"}}artifactNumToKeepStr{{/code}}: only this number of builds have their artifacts kept.
	39
	40	== Pipeline Triggers ==
	41
	42	Instead of having pipelines just triggered on source code changes you can also use cron syntax to define dates and times that shoud automatically trigger the pipeline.
	43
	44	{{code language="groovy" title="ℹ Example
	45	"}}
	46	properties([
	47	pipelineTriggers([cron('TZ=Europe/Berlin \n 00 08 * * 1-5')])
	48	])
	49	{{/code}}
	50
	51	The above example triggers the pipeline at 8:00 on Mo-Fr using the local German time. Without the TZ specification it will use the timezone of the Jenkins server which is UTC for DevOps-as-a-Service.
	52
	53	More about the cron spec is documented at [[https:~~/~~/jenkins.io/doc/book/pipeline/syntax/#cron-syntax>>url:https://jenkins.io/doc/book/pipeline/syntax/#cron-syntax\|\|shape="rect"]].
	54
	55	== Durability Settings ==
	56
	57	At the top of the Jenkinsfile add a durabilityHint to the properties:
	58
	59	{{code language="groovy" title="ℹ Example
	60	"}}
	61	properties([
	62	durabilityHint('PERFORMANCE_OPTIMIZED')
	63	])
	64	{{/code}}
	65
	66	The possible values and their meaning are documented at: [[https:~~/~~/jenkins.io/doc/book/pipeline/scaling-pipeline/>>url:https://jenkins.io/doc/book/pipeline/scaling-pipeline/\|\|shape="rect"]]
	67
	68	If unsure, please don't change the default!
	69
	70	= Automated building =
	71
	72	The best and easiest approach to use the power of Jenkins pipelines is to use the automatically provided [[doc:Jenkins.Jenkins Shared Library.WebHome]] which will detect the type of your project and automatically build and test it. The pipeline also provides optional deployments to target environments. See [[doc:Jenkins.Jenkins Shared Library.WebHome]] for more information!
	73
	74	= Building with tool plug-ins =
	75
	76	Some build tools have a special plug-in support in Jenkins which means you can easily call them on any Jenkins node. Jenkins will make sure to install and update them for you. In your Jenkinsfile you just refer with symbolic names to the major version of the tool you want to use. The DevOps-as-a-Service team will make sure that the latest Long Term Support (LTS) version of the tool will be automatically available for you. Most of the time these updates are done together with the update of your Jenkins controller instance.
	77
	78	We strive to make the exact version of the different tools publicly available on the start page of your Jenkins. See the screenshot below as an example. Put please check the current versions available to you at [[https:~~/~~/CUSTOMER.devops.t-systems.net/jenkins/>>url:https://CUSTOMER.devops.t-systems.net/jenkins/\|\|shape="rect"]] where CUSTOMER needs to be replaced by the name of your instance.
	79
	80	[[image:attach:image2022-11-10_10-27-6.png\|\|data-xwiki-image-style-border="true" queryparams="effects=drop-shadow" height="250"]]
	81
	82	== Maven ==
	83
	84	Supported symbolic name is 'maven'. The exact version can be looked up at the start page of your Jenkins, e.g. [[https:~~/~~/CUSTOMER.devops.t-systems.net/jenkins/>>url:https://CUSTOMER.devops.t-systems.net/jenkins/\|\|shape="rect"]]
	85
	86	{{code language="groovy" title="ℹ Scripted Pipeline
	87	"}}
	88	withMaven(maven: 'maven')
	89	{
	90	sh 'mvn --version'
	91	}
	92	{{/code}}
	93
	94	For more information about the withMaven pipeline step see [[https:~~/~~/www.jenkins.io/doc/pipeline/steps/pipeline-maven/>>url:https://www.jenkins.io/doc/pipeline/steps/pipeline-maven/\|\|shape="rect"]]. When you use the [[doc:Jenkins.Jenkins Shared Library.WebHome]] a maven build will be automatically done when a pom.xml file is found.
	95
	96	== JDK (Java Development Kit) ==
	97
	98	The supported symbolic names are listed at the start page of your Jenkins (e.g. [[https:~~/~~/CUSTOMER.devops.t-systems.net/jenkins/>>url:https://CUSTOMER.devops.t-systems.net/jenkins/\|\|shape="rect"]]) and start with 'jdk' or 'corretto'.
	99
	100	The following examples use jdk17.
	101
	102	{{code language="groovy" title="ℹ Scripted Pipeline
	103	"}}
	104	env.JAVA_HOME = "${tool 'jdk17'}"
	105	env.PATH="${env.JAVA_HOME}/bin:${env.PATH}"
	106	sh 'java -version'
	107	{{/code}}
	108
	109	When you use the [[doc:Jenkins.Jenkins Shared Library.WebHome]] you simply do
	110
	111	{{code language="groovy" title="ℹ Scripted Pipeline
	112	"}}
	113	@Library('sdcloud') _
	114
	115	sdcPipeline(jdk: 'jdk17')
	116	{{/code}}
	117
	118	to use the JDK version of your choice. See [[doc:Jenkins.Jenkins Shared Library.WebHome\|\|anchor="PipelineCustomization"]] for more information.
	119
	120	== nodejs ==
	121
	122	The supported symbolic names are listed at the start page of your Jenkins (e.g. [[https:~~/~~/CUSTOMER.devops.t-systems.net/jenkins/>>url:https://CUSTOMER.devops.t-systems.net/jenkins/\|\|shape="rect"]]) and start with 'nodejs'. As an example 'nodes16' would be refering to the latest release of nodejs v16. The short name 'nodejs' is usually set to the recommended LTS version of nodejs.
	123
	124	The following examples use 'nodejs18'.
	125
	126	{{code language="groovy" title="ℹ Scripted Pipeline
	127	"}}
	128	env.NODEJS_HOME = "${tool 'nodejs18'}"
	129	env.PATH="${env.NODEJS_HOME}/bin:${env.PATH}"
	130	sh 'node --version'
	131	sh 'npm --version'
	132	{{/code}}
	133
	134	When you use the [[doc:Jenkins.Jenkins Shared Library.WebHome]] you simply do
	135
	136	{{code language="groovy" title="ℹ Scripted Pipeline
	137	"}}
	138	@Library('sdcloud') _
	139
	140	sdcPipeline(nodejs: 'nodejs18')
	141	{{/code}}
	142
	143	to use the nodejs version of your choice. See [[doc:Jenkins.Jenkins Shared Library.WebHome\|\|anchor="PipelineCustomization"]] for more information.

Wiki source code of Jenkinsfile