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