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 completion by the
  74         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 completion by the
 166         Jenkins merge job that created and pushed the distribution files
 167         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 completion by the
 225         Jenkins merge job that created and pushed the distribution files
 226         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.
 306         **default**::
 307
 308             - compare-type: REG_EXP
 309               pattern: '(releases\/.*\.yaml|\.releases\/.*\.yaml)'
 310
 311
 312 Release Verify
 313 ~~~~~~~~~~~~~~
 314
 315 This template supports Maven and Container release jobs.
 316
 317 :Template Name: {project-name}-release-verify
 318
 319 :Comment Trigger: recheck|reverify
 320
 321 :Required Parameters:
 322
 323     :build-node: The node to run build on.
 324     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 325         in defaults.yaml)
 326     :project: Git repository name
 327     :project-name: Jenkins job name prefix
 328
 329 :Optional Parameters:
 330
 331     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 332     :build-node: The node to run build on.
 333     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 334     :gerrit-skip-vote: Skip voting for this job. (default: false)
 335     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 336
 337     :gerrit_verify_triggers: Override Gerrit Triggers.
 338     :gerrit_trigger_file_paths: Override file paths filter which checks which
 339         file modifications will trigger a build.
 340         **default**::
 341
 342             - compare-type: REG_EXP
 343               pattern: '(releases\/.*\.yaml|\.releases\/.*\.yaml)'
 344
 345
 346 PyPI Release Merge
 347 ~~~~~~~~~~~~~~~~~~
 348
 349 Publishes a Python package on merge of a patch set with a release yaml
 350 file. Checks the format of the version string, downloads the package
 351 artifacts from the PyPI staging repository, uploads the package
 352 artifacts to the PyPI release repository, tags the git repository,
 353 signs the tag and pushes the tag to the git server. The release merge
 354 template accepts neither a branch nor a stream parameter.
 355
 356 These templates use a git commit choosing strategy that builds the merged
 357 commit with the release yaml file, not the tip of the target branch, so
 358 projects can repeat the release action in case of merge job failure.
 359
 360 :Template Names:
 361
 362     - {project-name}-pypi-release-merge
 363     - gerrit-pypi-release-merge
 364     - github-pypi-release-merge
 365
 366 :Comment Trigger: remerge
 367
 368 :Required Parameters:
 369
 370     :build-node: The node to run build on, which must be Centos.
 371     :jenkins-ssh-release-credential: Credential to use for SSH. (Generally set
 372         in defaults.yaml)
 373     :project: Git repository name
 374     :project-name: Jenkins job name prefix
 375
 376 :Optional Parameters:
 377
 378     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 379     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 380     :disable-job: Whether to disable the job (default: false)
 381     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 382     :pypi-stage-index: Base URL of the PyPI staging repository.
 383         (default https://test.pypi.org/simple)
 384     :pypi-repo: Key for the PyPI release repository in the .pypirc file,
 385         should be the repository pypy.org. (default: pypi)
 386     :use-release-file: Whether to use the release file. (default: true)
 387
 388     :gerrit_trigger_file_paths: Override file paths filter which checks which
 389         file modifications will trigger a build.
 390         **default**::
 391
 392             - compare-type: REG_EXP
 393               pattern: '(releases\/pypi.*\.yaml|\.releases\/pypi.*\.yaml)'
 394
 395 PyPI Release Verify
 396 ~~~~~~~~~~~~~~~~~~~
 397
 398 Verifies a Python package project on creation of a patch set with a
 399 release yaml file. Checks the contents of the release yaml file,
 400 checks the format of the version string, and downloads the release
 401 artifacts from the specified PyPI staging repository. The release
 402 verify template accepts neither a branch nor a stream parameter.
 403
 404 :Template Names:
 405
 406     - {project-name}-pypi-release-verify
 407     - gerrit-pypi-release-verify
 408     - github-pypi-release-verify
 409
 410 :Comment Trigger: recheck
 411
 412 :Required Parameters:
 413
 414     :build-node: The node to run build on, which must be Centos.
 415     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 416         in defaults.yaml)
 417     :project: Git repository name
 418     :project-name: Jenkins job name prefix
 419
 420 :Optional Parameters:
 421
 422     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 423     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 424     :disable-job: Whether to disable the job (default: false)
 425     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 426     :pypi-stage-index: Base URL of the PyPI staging repository.
 427         (default https://test.pypi.org/simple)
 428     :pypi-repo: Key for the PyPI release repository in the .pypirc file,
 429         should be the repository pypy.org (default: pypi)
 430     :use-release-file: Whether to use the release file. (default: true)
 431
 432     :gerrit_trigger_file_paths: Override file paths filter which checks which
 433         file modifications will trigger a build.
 434         **default**::
 435
 436             - compare-type: REG_EXP
 437               pattern: '(releases\/pypi.*\.yaml|\.releases\/pypi.*\.yaml)'
 438
 439 PackageCloud Release Verify
 440 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 441
 442 This template supports PackageCloud release jobs. Checks that the specified
 443 packages are present in the staging repository and absent from the release
 444 repository.
 445
 446 :Template Name: {project-name}-packagecloud-release-verify
 447
 448 :Comment Trigger: recheck|reverify
 449
 450 :Required Parameters:
 451
 452     :build-node: The node to run build on.
 453     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 454         in defaults.yaml)
 455     :project: Git repository name
 456     :project-name: Jenkins job name prefix
 457
 458 :Optional Parameters:
 459
 460     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 461     :build-node: The node to run build on.
 462     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 463     :gerrit-skip-vote: Skip voting for this job. (default: false)
 464     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 465
 466     :gerrit_verify_triggers: Override Gerrit Triggers.
 467     :gerrit_trigger_file_paths: Override file paths filter which checks which
 468         file modifications will trigger a build.
 469         **default**::
 470
 471             - compare-type: REG_EXP
 472               pattern: '(releases\/packagecloud.*\.yaml|\.releases\/packagecloud.*\.yaml)'
 473
 474
 475 PackageCloud Release Merge
 476 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 477
 478 This template supports PackageCloud release jobs.  Promotes the specified
 479 packages from the staging repository to the release repository.
 480
 481 This template uses a git commit choosing strategy that builds the merged
 482 commit with the release yaml file, not the tip of the target branch, so
 483 projects can repeat the release action in case of merge job failure.
 484
 485 :template name: {project-name}-packagecloud-release-merge
 486
 487 :comment trigger: remerge
 488
 489 :required parameters:
 490
 491     :build-node: the node to run build on.
 492     :jenkins-ssh-release-credential: credential to use for ssh. (generally set
 493         in defaults.yaml)
 494     :project: git repository name
 495     :project-name: jenkins job name prefix
 496
 497 :optional parameters:
 498
 499     :build-days-to-keep: days to keep build logs in jenkins. (default: 7)
 500     :build-timeout: timeout in minutes before aborting build. (default: 15)
 501
 502     :gerrit_merge_triggers: override gerrit triggers.
 503     :gerrit_trigger_file_paths: override file paths filter which checks which
 504         file modifications will trigger a build.
 505         **default**::
 506
 507             - compare-type: reg_exp
 508               pattern: '(releases\/packagecloud.*\.yaml|\.releases\/packagecloud.*\.yaml)'
 509
 510
 511 Setup for LFID, Nexus, Jenkins and Gerrit
 512 -----------------------------------------
 513
 514 This section is for the Linux Foundation release engineering team.
 515
 516 LFID
 517 ~~~~
 518
 519 Create an ``lfid`` and an ``ssh-key``
 520
 521 ``YOUR_RELEASE_USERNAME`` for example: onap-release
 522
 523 ``YOUR_RELEASE_EMAIL`` for example: collab-it+onap-release@linuxfoundation.org
 524
 525 ssh-key example:
 526
 527 .. code-block:: bash
 528
 529    ssh-keygen -t rsa -C "collab-it+odl-release@linuxfoundation.org"  -f /tmp/odl-release
 530
 531
 532 `Create an LFID with the above values <https://identity.linuxfoundation.org>`_
 533
 534
 535 Nexus
 536 ~~~~~
 537
 538 Create a Nexus account called ``'jenkins-release'`` with promote privileges.
 539
 540 .. image:: ../_static/nexus-promote-privs.png
 541
 542 Gerrit
 543 ~~~~~~
 544
 545 Log into your Gerrit with ``YOUR_RELEASE_USERNAME``, upload the public
 546 part of the ``ssh-key`` you created earlier. Log out of Gerrit and log
 547 in again with your normal account for the next steps.
 548
 549
 550 In Gerrit create a new group called ``self-serve-release`` and give it
 551 direct push rights via ``All-Projects`` Add ``YOUR_RELEASE_USERNAME``
 552 to group ``self-serve-release`` and group ``Non-Interactive Users``
 553
 554
 555 In All project, grant group self-serve-release the following:
 556
 557 .. code-block:: none
 558
 559     [access "refs/heads/*"]
 560       push = group self-serve-release
 561     [access "refs/tags/*"]
 562       createTag = group self-serve-release
 563       createSignedTag = group self-serve-release
 564       forgeCommitter = group self-serve-release
 565       push = group self-serve-release
 566
 567
 568 Jenkins
 569 ~~~~~~~
 570
 571 Add a global credential to Jenkins called ``jenkins-release`` and set
 572 the ID: ``'jenkins-release'`` as its value insert the private half of
 573 the ``ssh-key`` that you created for your Gerrit user.
 574
 575 Add Global variables in Jenkins:
 576 Jenkins configure -> Global properties -> Environment variables::
 577
 578     RELEASE_USERNAME = YOUR_RELEASE_USERNAME
 579     RELEASE_EMAIL = YOUR_RELEASE_EMAIL
 580
 581
 582 .. note::
 583
 584     Add these variables to your global-vars-$SILO.sh file or they will
 585     be overwritten.
 586
 587 Jenkins configure -> Managed Files -> Add a New Config -> Custom File
 588
 589 .. code-block:: none
 590
 591     id: signing-pubkey
 592     Name: SIGNING_PUBKEY (optional)
 593     Comment: SIGNING_PUBKEY (optional)
 594
 595     Content: (Ask Andy for the public signing key)
 596     -----BEGIN PGP PUBLIC KEY BLOCK-----
 597
 598
 599 Add or edit the managed file in Jenkins called ``lftoolsini``,
 600 appending a nexus section: Jenkins Settings -> Managed files -> Add
 601 (or edit) -> Custom file
 602
 603 .. code-block:: none
 604
 605    [nexus.example.com]
 606    username=jenkins-release
 607    password=<plaintext password>
 608
 609 Ci-management
 610 ~~~~~~~~~~~~~
 611
 612 Upgrade your project's global-jjb if needed, then add the following to
 613 your global defaults file (e.g., jjb/defaults.yaml).
 614
 615 .. code-block:: none
 616
 617    jenkins-ssh-release-credential: jenkins-release