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