docs/jjb/lf-release-jobs.rst

   1 .. _lf-global-jjb-release:
   2
   3 #######################
   4 Self-Serve Release Jobs
   5 #######################
   6
   7 Self-serve release jobs allow a project team to direct Jenkins to
   8 promote a jar file or container image from a staging area to a release
   9 area.  To trigger the action, create a releases/ or .releases/
  10 directory, add a release yaml file to it, and submit a change set with
  11 one release yaml file to Gerrit.  Upon merge of the change, Jenkins will
  12 sign the reference extrapolated by log_dir and promote the artifact. The
  13 expected format of the release yaml file appears in schemas and examples
  14 below.
  15
  16 The build node for maven and container release jobs must be CentOS,
  17 which supports the sigul client for accessing a signing server. The
  18 build node for container release jobs must have Docker installed.
  19
  20 A Jenkins user can also trigger a release job via the "Build with
  21 parameters" action, removing the need for a release yaml file. The
  22 user must enter parameters in the same way as a release yaml file,
  23 except for the special USE_RELEASE_FILE and DRY_RUN check boxes. The
  24 user must uncheck the USE_RELEASE_FILE check box if the job should
  25 run with a release file, while passing the required information as
  26 build parameters. Similarly, the user must uncheck the DRY_RUN check
  27 box to test the job while skipping repository promotion to Nexus.
  28
  29 The special parameters are as follows::
  30
  31     GERRIT_BRANCH = master
  32     VERSION = 1.0.0
  33     LOG_DIR = example-project-maven-stage-master/17/
  34     DISTRIBUTION_TYPE = maven
  35     USE_RELEASE_FILE = false
  36     DRY_RUN = false
  37
  38 .. note::
  39
  40    The release file regex is: (releases\/.*\.yaml|\.releases\/.*\.yaml).
  41    In words, the directory name can be ".releases" or "releases"; the file
  42    name can be anything with suffix ".yaml".
  43
  44 The JSON schema for a maven release job appears below.
  45
  46 .. code-block:: none
  47
  48     ---
  49     $schema: "http://json-schema.org/schema#"
  50     $id: "https://github.com/lfit/releng-global-jjb/blob/master/release-schema.yaml"
  51
  52     required:
  53       - "distribution_type"
  54       - "log_dir"
  55       - "project"
  56       - "version"
  57
  58     properties:
  59       distribution_type:
  60         type: "string"
  61       log_dir:
  62         type: "string"
  63       project:
  64         type: "string"
  65       version:
  66         type: "string"
  67
  68
  69 Example of a maven release file:
  70
  71 .. code-block:: bash
  72
  73     $ cat releases/1.0.0-maven.yaml
  74     ---
  75     distribution_type: 'maven'
  76     version: '1.0.0'
  77     project: 'example-project'
  78     log_dir: 'example-project-maven-stage-master/17/'
  79
  80
  81 The JSON schema for a container release job appears below.
  82
  83 .. code-block:: none
  84
  85     ---
  86     $schema: "http://json-schema.org/schema#"
  87     $id: "https://github.com/lfit/releng-global-jjb/blob/master/release-container-schema.yaml"
  88
  89     required:
  90       - "containers"
  91       - "distribution_type"
  92       - "project"
  93       - "container_release_tag"
  94       - "ref"
  95
  96     properties:
  97       containers:
  98         type: "array"
  99         properties:
 100           name:
 101             type: "string"
 102           version:
 103             type: "string"
 104         additionalProperties: false
 105       distribution_type:
 106         type: "string"
 107       project:
 108         type: "string"
 109       container_release_tag:
 110         type: "string"
 111       ref:
 112         type: "string"
 113
 114
 115 An example of a container release file appears below.  The job applies the
 116 container_release_tag string to all released containers.  The job uses the
 117 per-container version strings to pull images from the container registry.
 118
 119 .. code-block:: bash
 120
 121     $ cat releases/1.0.0-container.yaml
 122     ---
 123     distribution_type: 'container'
 124     container_release_tag: '1.0.0'
 125     project: 'test'
 126     containers:
 127         - name: test-backend
 128           version: 1.0.0-20190806T184921Z
 129         - name: test-frontend
 130           version: 1.0.0-20190806T184921Z
 131
 132
 133 .. note::
 134
 135    Job should appear under gerrit-maven-stage
 136
 137 Example of a terse Jenkins job to call the global-jjb macro:
 138
 139 .. code-block:: none
 140
 141     - gerrit-maven-stage:
 142         sign-artifacts: true
 143         build-node: centos7-docker-8c-8g
 144         maven-versions-plugin: true
 145     - '{project-name}-gerrit-release-jobs':
 146         build-node: centos7-docker-8c-8g
 147
 148 .. note::
 149
 150    Release Engineers: please follow the setup guide below before adding the job definition.
 151
 152
 153 Setup for LFID, Nexus, Jenkins and Gerrit
 154 =========================================
 155
 156 LFID
 157 ====
 158
 159 Create an ``lfid`` and an ``ssh-key``
 160
 161 ``YOUR_RELEASE_USERNAME`` for example: onap-release
 162
 163 ``YOUR_RELEASE_EMAIL`` for example: collab-it+onap-release@linuxfoundation.org
 164
 165 ssh-key example:
 166
 167 .. code-block:: bash
 168
 169    ssh-keygen -t rsa -C "collab-it+odl-release@linuxfoundation.org"  -f /tmp/odl-release
 170
 171
 172 `Create an LFID with the above values <https://identity.linuxfoundation.org>`_
 173
 174
 175 Nexus
 176 =====
 177
 178 Create a Nexus account called ``'jenkins-release'`` with promote privileges.
 179
 180 .. image:: ../_static/nexus-promote-privs.png
 181
 182 Gerrit
 183 ======
 184
 185 Log into your Gerrit with ``YOUR_RELEASE_USERNAME``, upload the public
 186 part of the ``ssh-key`` you created earlier. Log out of Gerrit and log
 187 in again with your normal account for the next steps.
 188
 189
 190 In Gerrit create a new group called ``self-serve-release`` and give it
 191 direct push rights via ``All-Projects`` Add ``YOUR_RELEASE_USERNAME``
 192 to group ``self-serve-release`` and group ``Non-Interactive Users``
 193
 194
 195 In All project, grant group self-serve-release the following:
 196
 197 .. code-block:: none
 198
 199     [access "refs/heads/*"]
 200       push = group self-serve-release
 201     [access "refs/tags/*"]
 202       createTag = group self-serve-release
 203       createSignedTag = group self-serve-release
 204       forgeCommitter = group self-serve-release
 205       push = group self-serve-release
 206
 207
 208 Jenkins
 209 =======
 210
 211 Add a global credential to Jenkins called ``jenkins-release`` and set
 212 the ID: ``'jenkins-release'`` as its value insert the private half of
 213 the ``ssh-key`` that you created for your Gerrit user.
 214
 215 Add Global vars in Jenkins:
 216 Jenkins configure -> Global properties -> Environment variables
 217
 218 ``RELEASE_USERNAME = YOUR_RELEASE_USERNAME``
 219 ``RELEASE_EMAIL = YOUR_RELEASE_EMAIL``
 220
 221 Jenkins configure -> Managed Files -> Add a New Config -> Custom File
 222
 223 id: signing-pubkey
 224 Name: SIGNING_PUBKEY (optional)
 225 Comment: SIGNING_PUBKEY (optional)
 226
 227 Content: (Ask Andy for the public signing key)
 228 -----BEGIN PGP PUBLIC KEY BLOCK-----
 229
 230
 231 Add or edit the managed file in Jenkins called ``lftoolsini``,
 232 appending a nexus section: Jenkins Settings -> Managed files -> Add
 233 (or edit) -> Custom file
 234
 235 .. code-block:: none
 236
 237    [nexus.example.com]
 238    username=jenkins-release
 239    password=<plaintext password>
 240
 241 Ci-management
 242 =============
 243
 244 Upgrade your project's global-jjb if needed, then add the following to
 245 your global defaults file (e.g., jjb/defaults.yaml).
 246
 247 .. code-block:: none
 248
 249    jenkins-ssh-release-credential: 'jenkins-release'
 250
 251 Macros
 252 ======
 253
 254 lf-release
 255 ----------
 256
 257 Release verify and merge jobs are the same except for their scm,
 258 trigger, and builders definition. This anchor is the common template.
 259
 260 Job Templates
 261 =============
 262
 263 Release Merge
 264 -------------
 265
 266 :Template Name: {project-name}-release-merge
 267
 268 :Comment Trigger: remerge
 269
 270 :Required parameters:
 271
 272     :build-node: The node to run build on.
 273     :jenkins-ssh-release-credential: Credential to use for SSH. (Generally set
 274         in defaults.yaml)
 275     :stream: run this job against: **
 276
 277 :Optional parameters:
 278
 279     :branch: Git branch to fetch for the build. (default: all)
 280     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 281     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 282     :project-pattern: Project to trigger build against. (default: \*\*)
 283
 284     :gerrit_merge_triggers: Override Gerrit Triggers.
 285     :gerrit_trigger_file_paths: Override file paths filter which checks which
 286         file modifications will trigger a build.
 287         **default**::
 288
 289             - compare-type: REG_EXP
 290               pattern: '(releases\/.*\.yaml|\.releases\/.*\.yaml)'
 291
 292
 293 Release Verify
 294 ------------------
 295
 296 :Template Name: {project-name}-release-verify
 297
 298 :Comment Trigger: recheck|reverify
 299
 300 :Required Parameters:
 301
 302     :build-node: The node to run build on.
 303     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 304         in defaults.yaml)
 305     :stream: run this job against: **
 306
 307 :Optional Parameters:
 308
 309     :branch: Git branch to fetch for the build. (default: all)
 310     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 311     :build-node: The node to run build on.
 312     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 313     :doc-dir: Directory where tox will place built docs.
 314         as defined in the tox.ini (default: docs/_build/html)
 315     :gerrit-skip-vote: Skip voting for this job. (default: false)
 316     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 317     :project-pattern: Project to trigger build against. (default: \*\*)
 318
 319     :gerrit_verify_triggers: Override Gerrit Triggers.
 320     :gerrit_trigger_file_paths: Override file paths filter which checks which
 321         file modifications will trigger a build.
 322         **default**::
 323
 324             - compare-type: REG_EXP
 325               pattern: '(releases\/.*\.yaml|\.releases\/.*\.yaml)'