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