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