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