Revert "Minor cleanup of openstack-protect script"
[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 Parameters
378 ==========
379
380 lf-autotools-parameters
381 -----------------------
382
383 Provides parameters needed by configure and make. Use in any jobs that need to
384 call the ``configure && make`` pattern.
385
386 lf-clm-parameters
387 -----------------
388
389 Provides the policy evaluation stage to run against Nexus IQ Server.
390 Valid values include: 'build', 'stage-release', 'operate'.
391
392 lf-cmake-parameters
393 -------------------
394
395 Provides parameters required by CMake. Use in any jobs that need to call the
396 ``cmake && make && make install`` pattern.
397
398 lf-infra-maven-parameters
399 -------------------------
400
401 Provides parameters required by Maven. Use in any jobs that need to call the
402 ``mvn`` CLI.
403
404 lf-infra-openstack-parameters
405 -----------------------------
406
407 Provides parameters needed by OpenStack client CLI. Use in jobs that need to
408 call the openstack cli.
409
410 :Required Parameters:
411
412     :os-cloud: Configures ``OS_CLOUD`` envvar as used by openstack cli.
413
414 lf-infra-parameters
415 -------------------
416
417 Standard parameters used in the LF CI environments. GitHub projects will ignore
418 the Gerrit variables and vice-versa, so defining them is not harmful. Use in
419 every job template.
420
421 lf-infra-node-parameters
422 ------------------------
423
424 Provides parameters needed by NodeJS and NPM. Use in any jobs that need to run
425 NodeJS or NPM.
426
427 lf-infra-tox-parameters
428 -----------------------
429
430 Provides parameters required by python-tox. Use in any jobs that need to run
431 `tox <https://tox.readthedocs.io>`.
432
433
434 lf-build-with-parameters-maven-release
435 --------------------------------------
436
437 Provides parameters needed for maven release jobs 'build with parameters'.
438
439 Properties
440 ==========
441
442 lf-infra-properties
443 -------------------
444
445 Configures the build-discarder plugin for Jenkins with the recommended lf-infra
446 settings. We recommend to include in all job-templates.
447
448 Publishers
449 ==========
450
451 lf-jacoco-report
452 ----------------
453
454 Provides basic configuration for the JaCoCo plugin.
455
456 lf-infra-publish
457 ----------------
458
459 Provides basic lf-infra recommended publisher configurations for use in all job
460 templates. The purpose of this trigger is to gather package listing, instance
461 metadata, sar reports, build logs and copy them to a log server.
462
463 lf-infra-publish-windows
464 ------------------------
465
466 Windows publisher for use at the end of Windows job templates. Takes care of
467 cleaning out the workspace at the end of a job.
468
469 SCM
470 ===
471
472 lf-infra-gerrit-scm
473 -------------------
474
475 Basic SCM configuration for Gerrit based projects.
476
477 :Required parameters:
478
479     :submodule-timeout: Timeout (in minutes) for checkout operation.
480         (default: 10)
481     :submodule-disable: Disable submodule checkout operation.
482         (default: false)
483
484 lf-infra-github-scm
485 -------------------
486
487 Basic SCM configuration for GitHub based projects.
488
489 On the `branch` variable you can assign ``$sha1`` or ``$ghprbActualCommit``
490 as the value.  This will enable the jobs to trigger via the GHPRB plugin.
491
492 :Required parameters:
493
494     :submodule-timeout: Timeout (in minutes) for checkout operation.
495         (default: 10)
496     :submodule-disable: Disable submodule checkout operation.
497         (default: false)
498
499 Wrappers
500 ========
501
502 lf-infra-wrappers-common
503 ------------------------
504
505 Provides lf-infra recommended wrappers for use in every job-template. Include
506 this wrapper when creating more specific platform wrappers to ensure they pick
507 up the common settings.
508
509 lf-infra-wrappers
510 -----------------
511
512 Provides lf-infra recommended wrappers for use in every job-template targetting
513 Linux systems.
514
515 This wrapper requires a managed file named ``npmrc`` to exist in Jenkins. The
516 main use case here is to point to a npm proxy, on Nexus for example. Set the
517 file type to "Custom file".  You can set any npmrc settings in it,
518 documentation on npm configuration is available at
519 <https://docs.npmjs.com/files/npmrc>. If you are not using npm then create an
520 empty file.
521
522 Example npmrc:
523
524 .. code-block:: bash
525
526    registry=https://nexus3.onap.org/repository/npm.public/
527
528 lf-infra-wrappers-windows
529 -------------------------
530
531 Provides lf-infra recommended wrappers for use in every job-template targetting
532 Windows systems.