Merge "Handle S3_BUCKET & CDN_URL in release jobs"
[releng/global-jjb.git] / docs / jjb / lf-macros.rst
1 #############
2 Global Macros
3 #############
4
5 Builders
6 ========
7
8 comment-to-gerrit
9 -----------------
10
11 This macro will post a comment to the gerrit patchset if the build
12 creates a file named gerrit_comment.txt
13 To use this macro add it to the list of builders.
14
15
16 lf-fetch-dependent-patches
17 --------------------------
18
19 Fetch all patches provided via comment trigger
20
21 This macro will fetch all patches provided via comment trigger and will
22 create a list of projects from those patches via environment variable
23 called ``DEPENDENCY_BUILD_ORDER`` to build projects in the specified order.
24 Order calculated by the first patch instance for a project in the patch list.
25
26 lf-license-check
27 ----------------
28
29 Checks files for
30
31 :Required parameters:
32
33     :file-patterns: Space-separated list of file patterns to scan.
34         For example: \*.go \*.groovy \*.java \*.py \*.sh
35     :spdx-disable: Disable the SPDX-Identifier checker.
36     :lhc-version: Version of LHC to use.
37     :license-exclude-paths: Comma-separated list of paths to exclude from the
38         license checker. Matches the paths defined here using a contains rule,
39         we recommend you to configure as precisely as possible. For example
40         a path of '/src/generated/' will search as '**/src/generated/**'.
41         Example: org/opendaylight/yang/gen,protobuff/messages
42     :licenses-allowed: Comma-separated list of allowed licenses.
43         For example: Apache-2.0,EPL-1.0,MIT
44
45 lf-infra-capture-instance-metadata
46 ----------------------------------
47
48 Capture instance metadata.
49
50 lf-infra-create-netrc
51 ---------------------
52
53 Create a ~/.netrc file from a Maven settings.xml
54
55 :Required parameters:
56
57     :server-id: The id of a server as defined in settings.xml.
58
59 :Optional parameters:
60
61     :ALT_NEXUS_SERVER: URL of custom nexus server.
62         If set this will take precedence.
63         Use this to point at nexus3.$PROJECTDOMAIN
64         for example.
65
66 lf-infra-deploy-maven-file
67 --------------------------
68
69 Deploy files to a repository.
70
71 :Required parameters:
72
73     :global-settings-file: Global settings file to use.
74     :group-id: Group ID of the repository.
75     :maven-repo-url: URL of a Maven repository to upload to.
76     :mvn-version: Version of Maven to use.
77     :repo-id: Repository ID
78     :settings-file: Maven settings file to use.
79     :upload-files-dir: Path to directory containing one or more files
80
81 lf-infra-docker-login
82 ---------------------
83
84 Login into a custom hosted docker registry and / or docker.io
85
86 The Jenkins system should have the following global variables defined
87
88 :Environment variables:
89
90     :DOCKER_REGISTRY: The DNS address of the registry (IP or FQDN)
91         ex: nexus3.example.com (GLOBAL variable)
92
93     :REGISTRY_PORTS: Required when setting ``DOCKER_REGISTRY``. Space-separated
94         list of the registry ports to login to. ex: 10001 10002 10003 10004
95         (GLOBAL variable)
96
97     :DOCKERHUB_EMAIL: If set, then the job will attempt to login to DockerHub
98         (docker.io). Set to the email address for the credentials that will
99         get looked up. Returns the _first_ credential from the maven settings
100         file for DockerHub. (GLOBAL variable)
101
102 lf-infra-gpg-verify-git-signature
103 ---------------------------------
104
105 Verify gpg signature of the latest commit message in $WORKSPACE.
106 This command assumes that $WORKSPACE is a git repo.
107
108 lf-infra-pre-build
109 ------------------
110
111 Macro that runs before all builders to prepare the system for job use.
112
113 lf-infra-package-listing
114 ------------------------
115
116 Lists distro level packages.
117
118 lf-infra-packer-build
119 ---------------------
120
121 Run `packer build` to build system images.
122
123 :Required parameters:
124
125     :openstack: Packer template uses an OpenStack builder (true|false).
126     :openstack-cloud: Sets OS_CLOUD variable to the value of this parameter.
127     :packer-version: Version of packer to use.
128     :platform: Build platform as found in the vars directory.
129     :template: Packer template to build as found in the templates directory.
130
131 :Optional parameters:
132
133     :update-cloud-image: Submit a change request to update new built cloud
134         image to Jenkins.
135
136 lf-infra-packer-validate
137 ------------------------
138
139 Run ``packer validate`` to verify packer configuration.
140
141 :Required parameters:
142
143     :openstack: Packer template uses an OpenStack builder (true|false).
144     :openstack-cloud: Sets OS_CLOUD variable to the value of this parameter.
145     :packer-cloud-settings: Cloud configuration file. Loaded on the build
146         server as CLOUDENV environment variable.
147     :packer-version: Version of packer to use.
148
149 lf-infra-push-gerrit-patch
150 --------------------------
151
152 Push a change through a Jenkins job to a Gerrit repository in an automated
153 way using git-review.
154
155 :Required parameters:
156
157     :gerrit-commit-message: Commit message to assign.
158     :gerrit-host: Gerrit hostname.
159     :gerrit-topic: Gerrit topic.
160     :gerrit-user: Gerrit user-id used for submitting the change.
161     :reviewers-email: Reviewers email. Space-separated list of
162         email addresses to CC on the patch.
163     :project: Gerrit project name.
164
165 .. _lf-infra-ship-logs:
166
167 lf-infra-ship-logs
168 ------------------
169
170 Gather and deploy logs to a log server.
171
172 lf-infra-sysstat
173 ----------------
174
175 Retrieves system stats.
176
177 lf-infra-update-packer-images
178 -----------------------------
179
180 Find and update the new built cloud image{s} in the ci-management source
181 repository.
182
183
184 lf-jacoco-nojava-workaround
185 ---------------------------
186
187 Workaround for Jenkins not able to find Java in JaCoCo runs.
188
189 .. _lf-maven-central:
190
191 lf-maven-central
192 ----------------
193
194 Publish artifacts to OSSRH (Maven Central) staging.
195
196 Requires that the project's settings.xml contains a ServerId 'ossrh' with the
197 credentials for the project's OSSRH account.
198
199 This macro assumes the directory ``$WORKSPACE/m2repo`` contains a Maven 2
200 repository which is to upload to OSSRH.
201
202 :Required parameters:
203
204     :mvn-central: Set to ``true`` to upload to mvn-central. (true|false)
205     :mvn-global-settings: The name of the Maven global settings to use for
206         Maven configuration. (default: global-settings)
207     :mvn-settings: The name of settings file containing credentials for the
208         project.
209     :ossrh-profile-id: Nexus staging profile ID as provided by OSSRH.
210
211 .. literalinclude:: ../../.jjb-test/lf-macros/lf-maven-central-minimal.yaml
212    :language: yaml
213
214 .. _lf-maven-install:
215
216 lf-maven-install
217 ----------------
218
219 Call maven-target builder with a goal of ``--version`` to force Jenkins to
220 install the declared version of Maven. Use this as a preparation step for
221 any shell scripts that want to use Maven.
222
223 :Required parameters:
224
225     :mvn-version: Version of Maven to install.
226
227 lf-packagecloud-file-provider
228 -----------------------------
229
230 Provisions files required by the Ruby gem package_cloud, namely
231 ".packagecloud" and "packagecloud_api" in the Jenkins home directory.
232
233 lf-packagecloud-push
234 --------------------
235
236 Pushes DEB/RPM package files to PackageCloud using the Ruby gem package_cloud.
237
238 :Required parameters:
239
240     :build-dir: Directory with deb/rpm files to push
241     :debian-distribution-versions: list of DEB package distro/version strings
242         separated by space; example: ubuntu/bionic debian/stretch
243     :packagecloud-account: PackageCloud account ID; example: oran
244     :packagecloud-repo: PackageCloud repository; example: master, staging
245     :rpm-distribution-versions: list of RPM package distro/version strings
246         separated by space; example: el/4 el/5
247
248 lf-pip-install
249 --------------
250
251 Call pip install to install packages into a virtualenv located in
252 /tmp/v/VENV
253
254 .. note:: Uses the first package listed in PIP_PACKAGES as the VENV name.
255
256 .. _lf-provide-maven-settings:
257
258 lf-provide-maven-settings
259 -------------------------
260
261 Push a global settings and user settings maven files to the build node.
262
263 lf-provide-maven-settings-cleanup
264 ---------------------------------
265
266 Cleanup maven ``settings.xml`` configuration. Set at the end of any macros that
267 calls the
268 :ref:`lf-provide-maven-settings <lf-provide-maven-settings>` macro.
269
270 lf-rtd-trigger-build
271 --------------------
272
273 Script to trigger a build on http://readthedocs.org
274
275 lf-rtd-verify
276 -------------
277
278 ReadTheDocs verify script. Installs and runs tox.
279
280 :Required parameters:
281
282     :doc-dir: Document directory.
283     :python-version: Python version.
284
285 lf-rtdv3-build
286 ---------------
287
288 Read the docs scripts that leverage the new Read the Docs v3 api
289 `RTD v3 API <https://docs.readthedocs.io/en/stable/api/v3.html>`_
290 Runs tox to verify that the docs are good and then runs the RTDv3 shell script.
291 This script handles creating projects as needed, assiging subprojects to the main
292 read the docs project and triggering builds to update the documentation.
293 Jobs will run but skip verify bits until a ``.readthedocs.yaml`` exists in the
294 root of their repository.
295
296
297 check-info-votes
298 ----------------
299
300 Validates votes on a changes to ``INFO.yaml``.
301
302 lf-release
303 ----------
304
305 releases lftools.ini (required)
306 needed to push to nexus.
307
308 [nexus]
309 username=
310 password=
311
312 Then runs ../shell/release-job.sh
313
314
315 lf-sigul-sign-dir
316 -----------------
317
318 Use Sigul to sign a directory via {sign-dir}.
319
320 Requires ``SIGUL_BRIDGE_IP`` configured as a global envvar.
321
322 :Required Parameters:
323     :sign-artifacts: Set ``true`` to sign artifacts with Sigul.
324     :sign-dir: Directory to sign.
325     :sign-mode: serial|parallel
326
327 lf-infra-provide-docker-cleanup
328 -------------------------------
329
330 Forcefully removes all docker images.
331
332 lf-infra-sonar
333 ---------------
334
335 Runs Jenkins SonarQube plug-in.
336
337 Requires ``SonarQube Scanner for Jenkins``
338
339 .. note::
340
341     Optionally, set Sonar properties directly in the job definition by
342     setting the sonar-project-file to ``""`` and adding all properties under
343     ``sonar-properties``.
344
345 :Optional Parameters:
346     :sonar-task: Sonar task to run. (default: "")
347     :sonar-project-file: The filename for the project's properties
348         (default: "sonar-project.properties")
349     :sonar-properties: Sonar configuration properties. (default: "")
350     :sonar-java-opts: JVM options. (default: "")
351     :sonar-additional-args: Additional command line arguments. (default: "")
352
353 lf-infra-sonar-with-prescan
354 ---------------------------
355
356 Runs Jenkins SonarQube plug-in after a pre-scan builder.
357
358 Requires ``SonarQube Scanner for Jenkins``
359
360 .. note::
361
362     Optionally, set Sonar properties directly in the job definition by
363     setting the sonar-project-file to ``""`` and adding all properties under
364     ``sonar-properties``.
365
366 :Required Parameters:
367     :lf-sonar-prescan: A builder that will run before the Sonar scan.
368
369 :Optional Parameters:
370     :sonar-task: Sonar task to run. (default: "")
371     :sonar-project-file: The filename for the project's properties
372         (default: "sonar-project.properties")
373     :sonar-properties: Sonar configuration properties. (default: "")
374     :sonar-java-opts: JVM options. (default: "")
375     :sonar-additional-args: Additional command line arguments. (default: "")
376
377 lf-infra-pipeline-verify
378 ------------------------
379
380 Verify a Jenkins pipeline by linting it and ensuring that it cannot run on the
381 Jenkins master.
382
383 Parameters
384 ==========
385
386 lf-autotools-parameters
387 -----------------------
388
389 Provides parameters needed by configure and make. Use in any jobs that need to
390 call the ``configure && make`` pattern.
391
392 lf-clm-parameters
393 -----------------
394
395 Provides the policy evaluation stage to run against Nexus IQ Server.
396 Valid values include: 'build', 'stage-release', 'operate'.
397
398 lf-cmake-parameters
399 -------------------
400
401 Provides parameters required by CMake. Use in any jobs that need to call the
402 ``cmake && make && make install`` pattern.
403
404 lf-infra-maven-parameters
405 -------------------------
406
407 Provides parameters required by Maven. Use in any jobs that need to call the
408 ``mvn`` CLI.
409
410 lf-infra-openstack-parameters
411 -----------------------------
412
413 Provides parameters needed by OpenStack client CLI. Use in jobs that need to
414 call the openstack cli.
415
416 :Required Parameters:
417
418     :os-cloud: Configures ``OS_CLOUD`` envvar as used by openstack cli.
419
420 lf-infra-parameters
421 -------------------
422
423 Standard parameters used in the LF CI environments. GitHub projects will ignore
424 the Gerrit variables and vice-versa, so defining them is not harmful. Use in
425 every job template.
426
427 lf-infra-node-parameters
428 ------------------------
429
430 Provides parameters needed by NodeJS and NPM. Use in any jobs that need to run
431 NodeJS or NPM.
432
433 lf-infra-tox-parameters
434 -----------------------
435
436 Provides parameters required by python-tox. Use in any jobs that need to run
437 `tox <https://tox.readthedocs.io>`.
438
439
440 lf-build-with-parameters-maven-release
441 --------------------------------------
442
443 Provides parameters needed for maven release jobs 'build with parameters'.
444
445 Properties
446 ==========
447
448 lf-infra-properties
449 -------------------
450
451 Configures the build-discarder plugin for Jenkins with the recommended lf-infra
452 settings. We recommend to include in all job-templates.
453
454 Publishers
455 ==========
456
457 lf-jacoco-report
458 ----------------
459
460 Provides basic configuration for the JaCoCo plugin.
461
462 lf-infra-publish
463 ----------------
464
465 Provides basic lf-infra recommended publisher configurations for use in all job
466 templates. The purpose of this trigger is to gather package listing, instance
467 metadata, sar reports, build logs and copy them to a log server.
468
469 lf-infra-publish-windows
470 ------------------------
471
472 Windows publisher for use at the end of Windows job templates. Takes care of
473 cleaning out the workspace at the end of a job.
474
475 SCM
476 ===
477
478 lf-infra-gerrit-scm
479 -------------------
480
481 Basic SCM configuration for Gerrit based projects.
482
483 :Required parameters:
484
485     :submodule-timeout: Timeout (in minutes) for checkout operation.
486         (default: 10)
487     :submodule-disable: Disable submodule checkout operation.
488         (default: false)
489
490 lf-infra-github-scm
491 -------------------
492
493 Basic SCM configuration for GitHub based projects.
494
495 On the `branch` variable you can assign ``$sha1`` or ``$ghprbActualCommit``
496 as the value.  This will enable the jobs to trigger via the GHPRB plugin.
497
498 :Required parameters:
499
500     :submodule-timeout: Timeout (in minutes) for checkout operation.
501         (default: 10)
502     :submodule-disable: Disable submodule checkout operation.
503         (default: false)
504
505 Wrappers
506 ========
507
508 lf-infra-wrappers-common
509 ------------------------
510
511 Provides lf-infra recommended wrappers for use in every job-template. Include
512 this wrapper when creating more specific platform wrappers to ensure they pick
513 up the common settings.
514
515 lf-infra-wrappers
516 -----------------
517
518 Provides lf-infra recommended wrappers for use in every job-template targetting
519 Linux systems.
520
521 This wrapper requires a managed file named ``npmrc`` to exist in Jenkins. The
522 main use case here is to point to a npm proxy, on Nexus for example. Set the
523 file type to "Custom file".  You can set any npmrc settings in it,
524 documentation on npm configuration is available at
525 <https://docs.npmjs.com/files/npmrc>. If you are not using npm then create an
526 empty file.
527
528 Example npmrc:
529
530 .. code-block:: bash
531
532    registry=https://nexus3.onap.org/repository/npm.public/
533
534 lf-infra-wrappers-windows
535 -------------------------
536
537 Provides lf-infra recommended wrappers for use in every job-template targetting
538 Windows systems.
539
540
541 global-jjb-email-notification
542 -----------------------------
543
544 Provides a publisher macro that ties into the lf-openstack-cron job
545 to alert admins if this job fails.