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