724dad65f5d5489afcfa8f45f5126c838c7444b6
[releng/global-jjb.git] / lf-macros.rst
1 #############
2 Global Macros
3 #############
4
5 Builders
6 ========
7
8 lf-fetch-dependent-patches
9 --------------------------
10
11 Fetch all patches provided via comment trigger
12
13 This macro will fetch all patches provided via comment trigger and will
14 create a list of projects from those patches via environment variable
15 called DEPENDENCY_BUILD_ORDER which can be used if necessary to build
16 projects in the specified order. The order is determined by first patch
17 instance for a project in the patch list.
18
19 lf-infra-create-netrc
20 ---------------------
21
22 Create a ~/.netrc file from a Maven settings.xml
23
24 :Required parameters:
25
26     :server-id: The id of a server as defined in settings.xml.
27
28 :Optional parameters:
29
30     :ALT_NEXUS_SERVER: URL of custom nexus server.
31         If set this will take precedence.
32         Use this to point at nexus3.$PROJECTDOMAIN
33         for example.
34
35 lf-infra-deploy-maven-file
36 --------------------------
37
38 Deploy files to a repository.
39
40 :Required parameters:
41
42     :global-settings-file: Global settings file to use.
43     :group-id: Group ID of the repository.
44     :maven-repo-url: URL of a Maven repository to upload to.
45     :mvn-version: Version of Maven to use.
46     :repo-id: Repository ID
47     :settings-file: Maven settings file to use.
48     :upload-files-dir: Path to directory containing one or more files
49
50 lf-infra-docker-login
51 ---------------------
52
53 Login into a custom hosted docker registry and / or docker.io
54
55 The Jenkins system should have the following global variables defined
56
57 :Environment variables:
58
59     :DOCKER_REGISTRY: The DNS address of the registry (IP or FQDN)
60         ex: nexus3.example.com (GLOBAL variable)
61
62     :REGISTRY_PORTS: Required if DOCKER_REGISTRY is set. Space separated list
63         of the registry ports to login to. ex: 10001 10002 10003 10004
64         (GLOBAL variable)
65
66     :DOCKERHUB_EMAIL: If this variable is set then an attempt to login to
67         DockerHub (docker.io) will be also made. It should be set to the email
68         address for the credentials that will get looked up. Only _one_
69         credential will ever be found in the maven settings file for DockerHub.
70         (GLOBAL variable)
71
72 lf-infra-gpg-verify-git-signature
73 ---------------------------------
74
75 Verify gpg signature of the latest commit message in $WORKSPACE.
76 This command assumes that $WORKSPACE is a git repo.
77
78 lf-infra-packer-build
79 ---------------------
80
81 Run `packer build` to build system images.
82
83 lf-infra-packer-validate
84 ------------------------
85
86 Run `packer validate` to verify packer configuration.
87
88 :Required parameters:
89
90     :packer-cloud-settings: Cloud configuration file. Loaded on the build
91         server as CLOUDENV environment variable.
92     :packer-version: Version of packer to use.
93
94 lf-infra-ship-logs
95 ------------------
96
97 Gather and deploy logs to a log server.
98
99 lf-infra-sysstat
100 ----------------
101
102 Retrieves system stats.
103
104 lf-jacoco-nojava-workaround
105 ---------------------------
106
107 Workaround for Jenkins not able to find Java in JaCoCo runs.
108
109 lf-maven-install
110 ----------------
111
112 Call maven-target builder with a goal of --version to force Jenkins to
113 install the need provided version of Maven. This is needed for any shell scripts
114 that want to use Maven.
115
116 :Required parameters:
117
118     :mvn-version: Version of Maven to install.
119
120 lf-pip-install
121 --------------
122
123 Call pip install to install packages into a virtualenv located in
124 /tmp/v/VENV
125
126 .. note:: The first package listed in PIP_PACKAGES is used as the VENV name.
127
128 .. _lf-provide-maven-settings:
129
130 lf-provide-maven-settings
131 -------------------------
132
133 Push a global settings and user settings maven files to the build node.
134
135 lf-provide-maven-settings-cleanup
136 ---------------------------------
137
138 Cleanup maven settings.xml configuration. This should be called at the end of
139 any macros that calles the
140 :ref:`lf-provide-maven-settings <lf-provide-maven-settings>` macro.
141
142 lf-rtd-trigger-build
143 --------------------
144
145 Script to trigger a build on http://readthedocs.org
146
147 lf-rtd-verify
148 -------------
149
150 ReadTheDocs verify script.
151
152 Parameters
153 ==========
154
155 lf-infra-maven-parameters
156 -------------------------
157
158 Provides parameters needed by Maven. Should be used by any jobs that need to
159 call the mvn cli.
160
161 lf-infra-parameters
162 -------------------
163
164 Standard parameters used in the LF CI environments. Gerrit variables are
165 not used by GitHub projects, but defining them is not harmful. Should be used
166 in every job template.
167
168 lf-infra-node-parameters
169 ------------------------
170
171 Provides parameters needed by NodeJS and NPM. Should be used by any jobs that
172 need to run NodeJS or NPM.
173
174 lf-infra-tox-parameters
175 -----------------------
176
177 Provides parameters needed by python-tox. Should be used by any jobs that need
178 to run `tox <https://tox.readthedocs.io>`.
179
180 Properties
181 ==========
182
183 lf-infra-properties
184 -------------------
185
186 Configures the build-discarder plugin for Jenkins with the recommended lf-infra
187 settings. Should be used in all job-templates.
188
189 Publishers
190 ==========
191
192 lf-jacoco-report
193 ----------------
194
195 Provides basic configuration for the JaCoCo plugin.
196
197 lf-infra-publish
198 ----------------
199
200 Provides basic lf-infra recommended publisher configurations which should be
201 used in all job templates. This primary objective of this trigger is to
202 gather build logs and copy them to a log server.
203
204 SCM
205 ===
206
207 lf-infra-gerrit-scm
208 -------------------
209
210 Basic SCM configuration for Gerrit based projects.
211
212 lf-infra-github-scm
213 -------------------
214
215 Basic SCM configuration for GitHub based projects.
216
217 On the `branch` variable you can assign `$sha1` or `$ghprbActualCommit`
218 as the value.  This will require that the job be triggered via
219 the GHPRB plugin and not manually.
220
221 Triggers
222 ========
223
224 lf-infra-github-pr-trigger
225 --------------------------
226
227 Provides configuration for a GitHub PR Trigger.
228
229 Wrappers
230 ========
231
232 lf-infra-wrappers
233 -----------------
234
235 Provides lf-infra recommended wrappers which should be used in every
236 job-template.
237
238 This wrapper requires that a managed file called `npmrc` exists in the Jenkins.  The main use
239 case here is to point to a npm proxy, on Nexus for example.
240 The type of the file should be "Custom file".  You can set various npmrc settings in it.
241 Documentation on npm configuration can be found at https://docs.npmjs.com/files/npmrc.
242 If you are not using npm then it is fine for the file to be empty.
243
244 Example npmrc:
245
246 .. code-block:: bash
247
248    registry=https://nexus3.onap.org/repository/npm.public/