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