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/