docs/jjb/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 lf-infra-provide-docker-cleanup
 153 -------------------------------
 154
 155 Forcibly removes all of the docker images.
 156
 157 Parameters
 158 ==========
 159
 160 lf-infra-maven-parameters
 161 -------------------------
 162
 163 Provides parameters needed by Maven. Should be used by any jobs that need to
 164 call the mvn cli.
 165
 166 lf-infra-parameters
 167 -------------------
 168
 169 Standard parameters used in the LF CI environments. Gerrit variables are
 170 not used by GitHub projects, but defining them is not harmful. Should be used
 171 in every job template.
 172
 173 lf-infra-node-parameters
 174 ------------------------
 175
 176 Provides parameters needed by NodeJS and NPM. Should be used by any jobs that
 177 need to run NodeJS or NPM.
 178
 179 lf-infra-tox-parameters
 180 -----------------------
 181
 182 Provides parameters needed by python-tox. Should be used by any jobs that need
 183 to run `tox <https://tox.readthedocs.io>`.
 184
 185 Properties
 186 ==========
 187
 188 lf-infra-properties
 189 -------------------
 190
 191 Configures the build-discarder plugin for Jenkins with the recommended lf-infra
 192 settings. Should be used in all job-templates.
 193
 194 Publishers
 195 ==========
 196
 197 lf-jacoco-report
 198 ----------------
 199
 200 Provides basic configuration for the JaCoCo plugin.
 201
 202 lf-infra-publish
 203 ----------------
 204
 205 Provides basic lf-infra recommended publisher configurations which should be
 206 used in all job templates. This primary objective of this trigger is to
 207 gather build logs and copy them to a log server.
 208
 209 SCM
 210 ===
 211
 212 lf-infra-gerrit-scm
 213 -------------------
 214
 215 Basic SCM configuration for Gerrit based projects.
 216
 217 lf-infra-github-scm
 218 -------------------
 219
 220 Basic SCM configuration for GitHub based projects.
 221
 222 On the `branch` variable you can assign `$sha1` or `$ghprbActualCommit`
 223 as the value.  This will require that the job be triggered via
 224 the GHPRB plugin and not manually.
 225
 226 Triggers
 227 ========
 228
 229 lf-infra-github-pr-trigger
 230 --------------------------
 231
 232 Provides configuration for a GitHub PR Trigger.
 233
 234 Wrappers
 235 ========
 236
 237 lf-infra-wrappers
 238 -----------------
 239
 240 Provides lf-infra recommended wrappers which should be used in every
 241 job-template.
 242
 243 This wrapper requires that a managed file called `npmrc` exists in the Jenkins.  The main use
 244 case here is to point to a npm proxy, on Nexus for example.
 245 The type of the file should be "Custom file".  You can set various npmrc settings in it.
 246 Documentation on npm configuration can be found at https://docs.npmjs.com/files/npmrc.
 247 If you are not using npm then it is fine for the file to be empty.
 248
 249 Example npmrc:
 250
 251 .. code-block:: bash
 252
 253    registry=https://nexus3.onap.org/repository/npm.public/