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       container_pull_registry"
 112         type: "string"
 113       container_push_registry"
 114         type: "string"
 115       ref:
 116         type: "string"
 117
 118
 119 An example of a container release file appears below.  The job applies the
 120 container_release_tag string to all released containers.  The job uses the
 121 per-container version strings to pull images from the container registry.
 122
 123 .. code-block:: bash
 124
 125     $ cat releases/1.0.0-container.yaml
 126     ---
 127     distribution_type: 'container'
 128     container_release_tag: '1.0.0'
 129     container_pull_registry: 'nexus.onap.org:10003"
 130     container_push_registry: 'nexus.onap.org:10002"
 131     project: 'test'
 132     containers:
 133         - name: test-backend
 134           version: 1.0.0-20190806T184921Z
 135         - name: test-frontend
 136           version: 1.0.0-20190806T184921Z
 137
 138
 139 .. note::
 140
 141    Job should appear under gerrit-maven-stage
 142
 143 Example of a terse Jenkins job to call the global-jjb macro:
 144
 145 .. code-block:: none
 146
 147     - gerrit-maven-stage:
 148         sign-artifacts: true
 149         build-node: centos7-docker-8c-8g
 150         maven-versions-plugin: true
 151     - '{project-name}-gerrit-release-jobs':
 152         build-node: centos7-docker-8c-8g
 153
 154 .. note::
 155
 156    Release Engineers: please follow the setup guide below before adding the job definition.
 157
 158
 159 Setup for LFID, Nexus, Jenkins and Gerrit
 160 =========================================
 161
 162 LFID
 163 ====
 164
 165 Create an ``lfid`` and an ``ssh-key``
 166
 167 ``YOUR_RELEASE_USERNAME`` for example: onap-release
 168
 169 ``YOUR_RELEASE_EMAIL`` for example: collab-it+onap-release@linuxfoundation.org
 170
 171 ssh-key example:
 172
 173 .. code-block:: bash
 174
 175    ssh-keygen -t rsa -C "collab-it+odl-release@linuxfoundation.org"  -f /tmp/odl-release
 176
 177
 178 `Create an LFID with the above values <https://identity.linuxfoundation.org>`_
 179
 180
 181 Nexus
 182 =====
 183
 184 Create a Nexus account called ``'jenkins-release'`` with promote privileges.
 185
 186 .. image:: ../_static/nexus-promote-privs.png
 187
 188 Gerrit
 189 ======
 190
 191 Log into your Gerrit with ``YOUR_RELEASE_USERNAME``, upload the public
 192 part of the ``ssh-key`` you created earlier. Log out of Gerrit and log
 193 in again with your normal account for the next steps.
 194
 195
 196 In Gerrit create a new group called ``self-serve-release`` and give it
 197 direct push rights via ``All-Projects`` Add ``YOUR_RELEASE_USERNAME``
 198 to group ``self-serve-release`` and group ``Non-Interactive Users``
 199
 200
 201 In All project, grant group self-serve-release the following:
 202
 203 .. code-block:: none
 204
 205     [access "refs/heads/*"]
 206       push = group self-serve-release
 207     [access "refs/tags/*"]
 208       createTag = group self-serve-release
 209       createSignedTag = group self-serve-release
 210       forgeCommitter = group self-serve-release
 211       push = group self-serve-release
 212
 213
 214 Jenkins
 215 =======
 216
 217 Add a global credential to Jenkins called ``jenkins-release`` and set
 218 the ID: ``'jenkins-release'`` as its value insert the private half of
 219 the ``ssh-key`` that you created for your Gerrit user.
 220
 221 Add Global vars in Jenkins:
 222 Jenkins configure -> Global properties -> Environment variables
 223
 224 ``RELEASE_USERNAME = YOUR_RELEASE_USERNAME``
 225 ``RELEASE_EMAIL = YOUR_RELEASE_EMAIL``
 226
 227
 228 .. note::
 229
 230     These also need to be added to your global-vars-$SILO.sh
 231     or they will be overwritten.
 232
 233 Jenkins configure -> Managed Files -> Add a New Config -> Custom File
 234
 235 id: signing-pubkey
 236 Name: SIGNING_PUBKEY (optional)
 237 Comment: SIGNING_PUBKEY (optional)
 238
 239 Content: (Ask Andy for the public signing key)
 240 -----BEGIN PGP PUBLIC KEY BLOCK-----
 241
 242
 243 Add or edit the managed file in Jenkins called ``lftoolsini``,
 244 appending a nexus section: Jenkins Settings -> Managed files -> Add
 245 (or edit) -> Custom file
 246
 247 .. code-block:: none
 248
 249    [nexus.example.com]
 250    username=jenkins-release
 251    password=<plaintext password>
 252
 253 Ci-management
 254 =============
 255
 256 Upgrade your project's global-jjb if needed, then add the following to
 257 your global defaults file (e.g., jjb/defaults.yaml).
 258
 259 .. code-block:: none
 260
 261    jenkins-ssh-release-credential: 'jenkins-release'
 262
 263 Macros
 264 ======
 265
 266 lf-release
 267 ----------
 268
 269 Release verify and merge jobs are the same except for their scm,
 270 trigger, and builders definition. This anchor is the common template.
 271
 272 Job Templates
 273 =============
 274
 275 Release Merge
 276 -------------
 277
 278 :Template Name: {project-name}-release-merge
 279
 280 :Comment Trigger: remerge
 281
 282 :Required parameters:
 283
 284     :build-node: The node to run build on.
 285     :jenkins-ssh-release-credential: Credential to use for SSH. (Generally set
 286         in defaults.yaml)
 287     :stream: run this job against: **
 288
 289 :Optional parameters:
 290
 291     :branch: Git branch to fetch for the build. (default: all)
 292     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 293     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 294     :project-pattern: Project to trigger build against. (default: \*\*)
 295
 296     :gerrit_merge_triggers: Override Gerrit Triggers.
 297     :gerrit_trigger_file_paths: Override file paths filter which checks which
 298         file modifications will trigger a build.
 299         **default**::
 300
 301             - compare-type: REG_EXP
 302               pattern: '(releases\/.*\.yaml|\.releases\/.*\.yaml)'
 303
 304
 305 Release Verify
 306 ------------------
 307
 308 :Template Name: {project-name}-release-verify
 309
 310 :Comment Trigger: recheck|reverify
 311
 312 :Required Parameters:
 313
 314     :build-node: The node to run build on.
 315     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 316         in defaults.yaml)
 317     :stream: run this job against: **
 318
 319 :Optional Parameters:
 320
 321     :branch: Git branch to fetch for the build. (default: all)
 322     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 323     :build-node: The node to run build on.
 324     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 325     :doc-dir: Directory where tox will place built docs.
 326         as defined in the tox.ini (default: docs/_build/html)
 327     :gerrit-skip-vote: Skip voting for this job. (default: false)
 328     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 329     :project-pattern: Project to trigger build against. (default: \*\*)
 330
 331     :gerrit_verify_triggers: Override Gerrit Triggers.
 332     :gerrit_trigger_file_paths: Override file paths filter which checks which
 333         file modifications will trigger a build.
 334         **default**::
 335
 336             - compare-type: REG_EXP
 337               pattern: '(releases\/.*\.yaml|\.releases\/.*\.yaml)'