docs/jjb/lf-release-jobs.rst

   1 .. _lf-global-jjb-release:
   2
   3 Self-Serve Release Jobs
   4 =======================
   5
   6 Self-serve release jobs allow project committers to direct Jenkins to
   7 promote a jar file, container image or Python package from a staging
   8 area to a release area.
   9
  10 To use the self-release process, create a releases/ or .releases/
  11 directory at the root of the project repository, add one release yaml
  12 file to it, and submit a change set with that release yaml file.  The
  13 required contents of the release yaml file are different for each type
  14 of release, see the schemas and examples shown below.  The version in
  15 the release yaml file must be a valid Semantic Versioning (SemVer)
  16 string, matching either the pattern "v#.#.#" or "#.#.#" where "#" is
  17 one or more digits.  Upon merge of the change, Jenkins will sign the
  18 reference extrapolated by log_dir and promote the artifact.
  19
  20 .. note::
  21
  22    The release file regex is: (releases\/.*\.yaml|\.releases\/.*\.yaml).
  23    In words, the directory name can be ".releases" or "releases"; the file
  24    name can be anything with suffix ".yaml".
  25
  26 The build node for all release jobs must be CentOS, which supports the
  27 sigul client for accessing a signing server. The build node for
  28 container release jobs must have Docker installed.
  29
  30 A Jenkins admin user can also trigger a release job via the "Build
  31 with parameters" action, removing the need to create and merge a
  32 release yaml file.  The user must enter parameters in the same way as
  33 a release yaml file, except for the special USE_RELEASE_FILE and
  34 DRY_RUN check boxes. The user must uncheck the USE_RELEASE_FILE check
  35 box if the job should run without a release file, instead passing the
  36 required information as build parameters. The user can check the
  37 DRY_RUN check box to test the job while skipping upload of files to
  38 the release repository.
  39
  40 For example, the parameters for a Maven release are as follows::
  41
  42     GERRIT_BRANCH = master
  43     VERSION = 1.0.0
  44     LOG_DIR = example-project-maven-stage-master/17/
  45     DISTRIBUTION_TYPE = maven
  46     USE_RELEASE_FILE = false
  47     DRY_RUN = false
  48
  49 Maven Release Files
  50 -------------------
  51
  52 An example of a maven release file appears below.
  53
  54 .. code-block:: none
  55
  56     $ cat releases/maven-release.yaml
  57     ---
  58     distribution_type: maven
  59     log_dir: example-project-maven-stage-master/17/
  60     project: example-project
  61     version: 1.0.0
  62
  63
  64 The following parameters must appear in a maven release yaml file.
  65
  66 :Required Parameters:
  67
  68     :distribution_type: Must be "maven".
  69     :log_dir: The suffix of the logs URL reported on completion by the
  70         Jenkins stage job that created and pushed the artifact
  71         to the staging repository.  For example, use value
  72         "example-project-maven-stage-master/17" for the logs URL
  73         https://logs.lf-project.org/production/vex-sjc-lfp-jenkins-prod-1/example-project-maven-stage-master/17
  74     :project: The name of the project.
  75     :version: The semantic version string used for the artifact.
  76
  77 The JSON schema for a maven release file appears below.
  78
  79 .. code-block:: none
  80
  81     ---
  82     $schema: "http://json-schema.org/schema#"
  83     $id: "https://github.com/lfit/releng-global-jjb/blob/master/release-schema.yaml"
  84
  85     required:
  86       - "distribution_type"
  87       - "log_dir"
  88       - "project"
  89       - "version"
  90
  91     properties:
  92       distribution_type:
  93         type: "string"
  94       log_dir:
  95         type: "string"
  96       project:
  97         type: "string"
  98       version:
  99         type: "string"
 100
 101
 102 Container Release Files
 103 -----------------------
 104
 105 An example of a container release file appears below.
 106
 107 .. code-block:: none
 108
 109     $ cat releases/container-release.yaml
 110     ---
 111     distribution_type: container
 112     container_release_tag: 1.0.0
 113     container_pull_registry: nexus.onap.org:10003
 114     container_push_registry: nexus.onap.org:10002
 115     project: test
 116     ref: d1b9cd2dd345fbeec0d3e2162e008358b8b663b2
 117     containers:
 118         - name: test-backend
 119           version: 1.0.0-20190806T184921Z
 120         - name: test-frontend
 121           version: 1.0.0-20190806T184921Z
 122
 123
 124 The following parameters must appear in a container release yaml file.
 125
 126 :Required Parameters:
 127
 128     :distribution_type: Must be "container".
 129     :container_release_tag: The string to use as a Docker tag on all
 130         released containers.
 131     :container_pull_registry: The Nexus registry that supplies the staged
 132         image(s).
 133     :container_push_registry: The Nexus registry that receives the released
 134         image(s).
 135     :project: The name of the project.
 136     :ref: The git commit reference (SHA-1 code) to tag with the version string.
 137     :containers: A list of name and version (tag) pairs that specify the
 138         Docker images in the container-pull registry to promote to the
 139         container-push registry.
 140
 141 The JSON schema for a container release file appears below.
 142
 143 .. code-block:: none
 144
 145     ---
 146     $schema: "http://json-schema.org/schema#"
 147     $id: "https://github.com/lfit/releng-global-jjb/blob/master/release-container-schema.yaml"
 148
 149     required:
 150       - "containers"
 151       - "distribution_type"
 152       - "project"
 153       - "container_release_tag"
 154       - "ref"
 155
 156     properties:
 157       containers:
 158         type: "array"
 159         properties:
 160           name:
 161             type: "string"
 162           version:
 163             type: "string"
 164         additionalProperties: false
 165       distribution_type:
 166         type: "string"
 167       project:
 168         type: "string"
 169       container_release_tag:
 170         type: "string"
 171       container_pull_registry"
 172         type: "string"
 173       container_push_registry"
 174         type: "string"
 175       ref:
 176         type: "string"
 177
 178
 179 PyPI Release Files
 180 ------------------
 181
 182 An example of a PyPI release file appears below.
 183
 184 .. code-block:: none
 185
 186     $ cat releases/pypi-release.yaml
 187     ---
 188     distribution_type: pypi
 189     pypi_project: mypackage
 190     python_version: '3.4'
 191     version: 1.0.0
 192
 193
 194 The following parameters must appear in the PyPI release yaml file.
 195 These are not part of the Jenkins job definition to allow independent
 196 self-release of a package maintained in a git repository with other
 197 packages.
 198
 199 :Required Parameters:
 200
 201     :distribution_type: Must be "pypi".
 202     :log_dir: The suffix of the logs URL reported on completion by the
 203         Jenkins merge job that created and pushed the distribution files
 204         to the staging repository.  For example, use value
 205         "example-project-pypi-merge-master/17" for the logs URL
 206         https://logs.lf-project.org/production/vex-sjc-lfp-jenkins-prod-1/example-project-pypi-merge-master/17
 207     :pypi_project: The PyPI project name at the staging and
 208         release repositories, for example "mypackage".
 209     :python_version: The Python interpreter version to use for pip
 210         "Requires-Python" compatibility checks, for example '3', '3.7' or 3.7.4.
 211         Put valid decimal values such as 3 or 3.7 in quotes to pass schema validation.
 212     :version: The semantic version string used for the package in the
 213         setup.py file.
 214
 215 The JSON schema for a PyPI release file appears below.
 216
 217 .. code-block:: none
 218
 219     ---
 220     $schema: "http://json-schema.org/schema#"
 221     $id: "https://github.com/lfit/releng-global-jjb/blob/master/release-pypi-schema.yaml"
 222
 223     required:
 224       - "distribution_type"
 225       - "log_dir"
 226       - "pypi_project"
 227       - "python_version"
 228       - "version"
 229
 230     properties:
 231       distribution_type:
 232         type: "string"
 233       log_dir:
 234         type: "string"
 235       pypi_project:
 236         type: "string"
 237       python_version:
 238         type: "string"
 239       version:
 240         type: "string"
 241
 242
 243 Jenkins Jobs
 244 ------------
 245
 246 An example of a Jenkins job configuration that uses the global-jjb
 247 templates for maven and container release jobs appears next.
 248
 249 .. code-block:: none
 250
 251     - project:
 252         name: my-project-release
 253         project: my-project
 254         project-name: my-project
 255         build-node: centos7-docker-4c-4g
 256         mvn-settings: my-project-settings
 257         jobs:
 258             - '{project-name}-gerrit-release-jobs'
 259
 260
 261 .. note::
 262
 263    Release Engineers: please follow the setup guide below before adding the job definition.
 264
 265
 266 JJB Macros
 267 ----------
 268
 269 lf-release
 270 ~~~~~~~~~~
 271
 272 Release verify and merge jobs are the same except for their scm,
 273 trigger, and builders definition. This anchor is the common template.
 274
 275 JJB Templates
 276 -------------
 277
 278 Release Merge
 279 ~~~~~~~~~~~~~
 280
 281 This template supports Maven and Container release jobs.
 282
 283 :Template Name: {project-name}-release-merge
 284
 285 :Comment Trigger: remerge
 286
 287 :Required parameters:
 288
 289     :build-node: The node to run build on.
 290     :jenkins-ssh-release-credential: Credential to use for SSH. (Generally set
 291         in defaults.yaml)
 292     :project: Git repository name
 293     :project-name: Jenkins job name prefix
 294
 295 :Optional parameters:
 296
 297     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 298     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 299
 300     :gerrit_merge_triggers: Override Gerrit Triggers.
 301     :gerrit_trigger_file_paths: Override file paths filter which checks which
 302         file modifications will trigger a build.
 303         **default**::
 304
 305             - compare-type: REG_EXP
 306               pattern: '(releases\/.*\.yaml|\.releases\/.*\.yaml)'
 307
 308
 309 Release Verify
 310 ~~~~~~~~~~~~~~
 311
 312 This template supports Maven and Container release jobs.
 313
 314 :Template Name: {project-name}-release-verify
 315
 316 :Comment Trigger: recheck|reverify
 317
 318 :Required Parameters:
 319
 320     :build-node: The node to run build on.
 321     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 322         in defaults.yaml)
 323     :project: Git repository name
 324     :project-name: Jenkins job name prefix
 325
 326 :Optional Parameters:
 327
 328     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 329     :build-node: The node to run build on.
 330     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 331     :gerrit-skip-vote: Skip voting for this job. (default: false)
 332     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 333
 334     :gerrit_verify_triggers: Override Gerrit Triggers.
 335     :gerrit_trigger_file_paths: Override file paths filter which checks which
 336         file modifications will trigger a build.
 337         **default**::
 338
 339             - compare-type: REG_EXP
 340               pattern: '(releases\/.*\.yaml|\.releases\/.*\.yaml)'
 341
 342
 343 PyPI Release Merge
 344 ~~~~~~~~~~~~~~~~~~
 345
 346 Publishes a Python package on merge of a patch set with a release yaml
 347 file. Checks the format of the version string, downloads the package
 348 artifacts from the PyPI staging repository, uploads the package
 349 artifacts to the PyPI release repository, tags the git repository,
 350 signs the tag and pushes the tag to the git server. The release verify
 351 template accepts neither a branch nor a stream parameter.
 352
 353 :Template Names:
 354
 355     - {project-name}-pypi-release-merge
 356     - gerrit-pypi-release-merge
 357     - github-pypi-release-merge
 358
 359 :Comment Trigger: remerge
 360
 361 :Required Parameters:
 362
 363     :build-node: The node to run build on, which must be Centos.
 364     :jenkins-ssh-release-credential: Credential to use for SSH. (Generally set
 365         in defaults.yaml)
 366     :project: Git repository name
 367     :project-name: Jenkins job name prefix
 368
 369 :Optional Parameters:
 370
 371     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 372     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 373     :disable-job: Whether to disable the job (default: false)
 374     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 375     :pypi-stage-index: Base URL of the PyPI staging repository.
 376         (default https://test.pypi.org/simple)
 377     :pypi-repo: Key for the PyPI release repository in the .pypirc file,
 378         should be the repository pypy.org. (default: pypi)
 379     :use-release-file: Whether to use the release file. (default: true)
 380
 381
 382 PyPI Release Verify
 383 ~~~~~~~~~~~~~~~~~~~
 384
 385 Verifies a Python package project on creation of a patch set with a
 386 release yaml file. Checks the contents of the release yaml file,
 387 checks the format of the version string, and downloads the release
 388 artifacts from the specified PyPI staging repository. The release
 389 verify template accepts neither a branch nor a stream parameter.
 390
 391 :Template Names:
 392
 393     - {project-name}-pypi-release-verify
 394     - gerrit-pypi-release-verify
 395     - github-pypi-release-verify
 396
 397 :Comment Trigger: recheck
 398
 399 :Required Parameters:
 400
 401     :build-node: The node to run build on, which must be Centos.
 402     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 403         in defaults.yaml)
 404     :project: Git repository name
 405     :project-name: Jenkins job name prefix
 406
 407 :Optional Parameters:
 408
 409     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 410     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 411     :disable-job: Whether to disable the job (default: false)
 412     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 413     :pypi-stage-index: Base URL of the PyPI staging repository.
 414         (default https://test.pypi.org/simple)
 415     :pypi-repo: Key for the PyPI release repository in the .pypirc file,
 416         should be the repository pypy.org (default: pypi)
 417     :use-release-file: Whether to use the release file. (default: true)
 418
 419
 420 Setup for LFID, Nexus, Jenkins and Gerrit
 421 -----------------------------------------
 422
 423 This section is for the Linux Foundation release engineering team.
 424
 425 LFID
 426 ~~~~
 427
 428 Create an ``lfid`` and an ``ssh-key``
 429
 430 ``YOUR_RELEASE_USERNAME`` for example: onap-release
 431
 432 ``YOUR_RELEASE_EMAIL`` for example: collab-it+onap-release@linuxfoundation.org
 433
 434 ssh-key example:
 435
 436 .. code-block:: bash
 437
 438    ssh-keygen -t rsa -C "collab-it+odl-release@linuxfoundation.org"  -f /tmp/odl-release
 439
 440
 441 `Create an LFID with the above values <https://identity.linuxfoundation.org>`_
 442
 443
 444 Nexus
 445 ~~~~~
 446
 447 Create a Nexus account called ``'jenkins-release'`` with promote privileges.
 448
 449 .. image:: ../_static/nexus-promote-privs.png
 450
 451 Gerrit
 452 ~~~~~~
 453
 454 Log into your Gerrit with ``YOUR_RELEASE_USERNAME``, upload the public
 455 part of the ``ssh-key`` you created earlier. Log out of Gerrit and log
 456 in again with your normal account for the next steps.
 457
 458
 459 In Gerrit create a new group called ``self-serve-release`` and give it
 460 direct push rights via ``All-Projects`` Add ``YOUR_RELEASE_USERNAME``
 461 to group ``self-serve-release`` and group ``Non-Interactive Users``
 462
 463
 464 In All project, grant group self-serve-release the following:
 465
 466 .. code-block:: none
 467
 468     [access "refs/heads/*"]
 469       push = group self-serve-release
 470     [access "refs/tags/*"]
 471       createTag = group self-serve-release
 472       createSignedTag = group self-serve-release
 473       forgeCommitter = group self-serve-release
 474       push = group self-serve-release
 475
 476
 477 Jenkins
 478 ~~~~~~~
 479
 480 Add a global credential to Jenkins called ``jenkins-release`` and set
 481 the ID: ``'jenkins-release'`` as its value insert the private half of
 482 the ``ssh-key`` that you created for your Gerrit user.
 483
 484 Add Global variables in Jenkins:
 485 Jenkins configure -> Global properties -> Environment variables::
 486
 487     RELEASE_USERNAME = YOUR_RELEASE_USERNAME
 488     RELEASE_EMAIL = YOUR_RELEASE_EMAIL
 489
 490
 491 .. note::
 492
 493     Add these variables to your global-vars-$SILO.sh file or they will
 494     be overwritten.
 495
 496 Jenkins configure -> Managed Files -> Add a New Config -> Custom File
 497
 498 .. code-block:: none
 499
 500     id: signing-pubkey
 501     Name: SIGNING_PUBKEY (optional)
 502     Comment: SIGNING_PUBKEY (optional)
 503
 504     Content: (Ask Andy for the public signing key)
 505     -----BEGIN PGP PUBLIC KEY BLOCK-----
 506
 507
 508 Add or edit the managed file in Jenkins called ``lftoolsini``,
 509 appending a nexus section: Jenkins Settings -> Managed files -> Add
 510 (or edit) -> Custom file
 511
 512 .. code-block:: none
 513
 514    [nexus.example.com]
 515    username=jenkins-release
 516    password=<plaintext password>
 517
 518 Ci-management
 519 ~~~~~~~~~~~~~
 520
 521 Upgrade your project's global-jjb if needed, then add the following to
 522 your global defaults file (e.g., jjb/defaults.yaml).
 523
 524 .. code-block:: none
 525
 526    jenkins-ssh-release-credential: jenkins-release