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 directory and then place a release file in it.
   8 Jenkins will pick this up and then promote the artifact from the staging log directory (log_dir) and tag the release
   9 with the defined version. maven_central_url is optional
  10
  11 .. note::
  12
  13    Example of a project's release file:
  14
  15 .. code-block:: bash
  16
  17    $ cat releases/1.0.0.yaml
  18    ---
  19    distribution_type: 'maven'
  20    version: '1.0.0'
  21    project: 'example-test-release'
  22    log_dir: 'example-test-release-maven-stage-master/17/'
  23    maven_central_url: 'oss.sonatype.org'
  24
  25 .. note::
  26
  27    Example of a terse Jenkins job to call global-jjb macro:
  28
  29 .. code-block:: none
  30
  31    - project:
  32        name: '{project-name}-gerrit-release-jobs'
  33        project: 'example-test-release'
  34        build-node: centos7-builder-2c-1g
  35        project-name: example-test-release
  36        jobs:
  37          - '{project-name}-gerrit-release-jobs'
  38
  39 .. note::
  40
  41    Example of a verbose Jenkins job to call global-jjb macro:
  42
  43 .. code-block:: none
  44
  45    - project:
  46        name: '{project-name}-releases-verify'
  47        project: 'example-test-release'
  48        build-node: centos7-builder-2c-1g
  49        project-name: example-test-release
  50        jobs:
  51          - 'gerrit-releases-verify'
  52
  53 .. code-block:: none
  54
  55    - project:
  56        name: '{project-name}-releases-merge'
  57        project: 'example-test-release'
  58        build-node: centos7-builder-2c-1g
  59        project-name: example-test-release
  60        jobs:
  61          - 'gerrit-releases-merge'
  62
  63 .. note::
  64
  65    Release Engineers Please follow the setup guide before adding the job definition:
  66
  67 Setup for LFID Nexus Jenkins and Gerrit:
  68 ========================================
  69
  70 LFID
  71 ====
  72
  73 Create an ``lfid`` and an ``ssh-key``
  74
  75 ``RELEASE_USERNAME``
  76 ``RELEASE_EMAIL``
  77
  78 ssh-key example:
  79
  80 .. code-block:: bash
  81
  82    ssh-keygen -t rsa -C "collab-it+odl-release@linuxfoundation.org"  -f /tmp/odl-release
  83
  84
  85 `Create an LFID <https://identity.linuxfoundation.org>`_
  86
  87 Nexus
  88 =====
  89
  90 Create a Nexus account called ``'jenkins-release'`` with promote privileges.
  91
  92 .. image:: ../_static/nexus-promote-privs.png
  93
  94 Gerrit
  95 ======
  96
  97 Log into your Gerrit with ``RELEASE_USERNAME``, upload the ``ssh-key`` you created earlier.
  98 Log out of Gerrit and log in again with your normal account for the next steps.
  99
 100 In Gerrit create a new group called ``self-serve-release`` and give it direct push rights via ``All-Projects``
 101 ``push - refs/heads/*``
 102
 103 1. Add a push reference
 104 2. Set the ref as refs/heads/*
 105 3. Make sure "force push" is not checked
 106
 107 Add ``RELEASE_USERNAME`` to group ``self-serve-release`` and group ``Non-Interactive Users``
 108
 109 Give group ``self-serve-release`` Forge Committer rights on ``refs/tags/*``
 110 Give group ``self-serve-release`` Allow on ``Create Signed Tag``
 111 Give group ``self-serve-release`` Allow on ``Create Annotated Tag``
 112
 113 Jenkins
 114 =======
 115
 116 Add a global credential to Jenkins called ``jenkins-release`` and set the ID: ``'jenkins-release'``
 117 as its value insert the ``ssh-key`` that you uploaded to Gerrit.
 118
 119 Add Global vars in Jenkins:
 120 Jenkins configre -> Global properties -> Environment variables
 121
 122 ``RELEASE_USERNAME = $RELEASE_USERNAME``
 123 ``RELEASE_EMAIL = $RELEASE_EMAIL``
 124
 125 Jenkins configre -> Managed Files -> Custom File
 126
 127 id: signing-pubkey
 128 Name: SIGNING_PUBKEY (optional)
 129 Comment: SIGNING_PUBKEY (optional)
 130
 131 Content: (ask andy)
 132 -----BEGIN PGP PUBLIC KEY BLOCK-----
 133
 134
 135 Add or edit the managed file in Jenkins called ``lftoolsini``, appending a nexus section:
 136 Jenkins Settings -> Managed files -> Add (or edit) -> Custom file
 137
 138 .. code-block:: none
 139
 140    [nexus]
 141    username=jenkins-release
 142    password=redacted
 143
 144 Ci-management
 145 =============
 146
 147 upgrade you projects global-jjb if needed
 148 add this to your global defaults file (eg: jjb/defaults.yaml)
 149
 150 .. code-block:: bash
 151
 152    jenkins-ssh-release-credential: 'jenkins-release'
 153
 154 Macros
 155 ======
 156
 157 lf-release
 158 ----------
 159
 160 Release verify and merge jobs are the same except for their scm, trigger, and
 161 builders definition. This anchor is the common template.
 162
 163 Job Templates
 164 =============
 165
 166 Release Merge
 167 -------------
 168
 169 Runs:
 170
 171 - sigul-install
 172 - sigul-configuration
 173 - checkout ref from taglist.log
 174 - applies the $PROJECT.bundle
 175 - signs, tags and pushes
 176
 177 .. code-block:: bash
 178
 179    lftools nexus release --server $NEXUS_URL $STAGING_REPO
 180
 181
 182 :Template Name:
 183     - {project-name}-release-merge-{stream}
 184
 185 :Comment Trigger: remerge
 186
 187 :Required parameters:
 188
 189     :build-node: The node to run build on.
 190     :jenkins-ssh-release-credential: Credential to use for SSH. (Generally set
 191         in defaults.yaml)
 192     :stream: run this job against: master
 193
 194 :Optional parameters:
 195
 196     :branch: Git branch to fetch for the build. (default: master)
 197     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 198     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 199     :project-pattern: Project to trigger build against. (default: \*\*)
 200
 201     :gerrit_merge_triggers: Override Gerrit Triggers.
 202     :gerrit_trigger_file_paths: Override file paths filter which checks which
 203         file modifications will trigger a build.
 204         **default**::
 205
 206             - compare-type: ANT
 207               pattern: 'releases/*.yaml'
 208
 209
 210 Release Verify
 211 ------------------
 212
 213 Release verify job checks the schema and ensures that the staging-repo.txt.gz
 214 is available on the job.
 215
 216 - sigul-install
 217 - sigul-configuration
 218 - checkout ref from taglist.log
 219 - applies the $PROJECT.bundle
 220 - signs and shows signature
 221
 222
 223 :Template Names:
 224     - {project-name}-release-verify-{stream}
 225
 226 :Comment Trigger: recheck|reverify
 227
 228 :Required Parameters:
 229
 230     :build-node: The node to run build on.
 231     :jenkins-ssh-release-credential: Credential to use for SSH. (Generally set
 232         in defaults.yaml)
 233     :stream: run this job against: master
 234
 235 :Optional Parameters:
 236
 237     :branch: Git branch to fetch for the build. (default: master)
 238     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 239     :build-node: The node to run build on.
 240     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 241     :doc-dir: Directory where tox will place built docs.
 242         as defined in the tox.ini (default: docs/_build/html)
 243     :gerrit-skip-vote: Skip voting for this job. (default: false)
 244     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 245     :project-pattern: Project to trigger build against. (default: \*\*)
 246
 247     :gerrit_verify_triggers: Override Gerrit Triggers.
 248     :gerrit_trigger_file_paths: Override file paths filter which checks which
 249         file modifications will trigger a build.
 250         **default**::
 251
 252             - compare-type: ANT
 253               pattern: 'releases/*.yaml'