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-1.6.0
 200     packages:
 201         - name: tree-1.6.0-10.el7.x86_64.rpm
 202         - name: test.rpm
 203     ref: 5555cd2dd345fbeec0d3e2162e00835852342cda
 204     log_dir: example-project-packagecloud-merge/21
 205     version: 1.6.0
 206
 207 The following parameters must appear in the PackageCloud release yaml file.
 208 These are not part of the Jenkins job definition to allow independent
 209 self-release of a package maintained in a git repository with other
 210 packages.
 211
 212 :Required Parameters:
 213
 214     :package_name: Name of the release package.
 215     :packages: A list of names that specify the packages to promote.
 216         Found in jenkins console log when using gem to push package eg.
 217         "Pushing /path/of/package/name-of-package.rpm... success!"
 218         OR using rest api call to query packagecloud.io repo
 219         "curl https://packagecloud.io/api/v1/repos/test_user/test_repo/search?q=
 220         | yq -r .[].filename"
 221     :ref: The git commit reference (SHA-1 code) to tag with the version string.
 222     :log_dir: The suffix of the logs URL reported on completion by the
 223         Jenkins merge job that created and pushed the distribution files
 224         to the staging repository. For example, use value
 225         "example-project-packagecloud-merge-/21" for the logs URL
 226         https://logs.lf-project.org/production/vex-sjc-lfp-jenkins-prod-1/example-project-packagecloud-merge/21
 227     :version: The semantic version string used for the package.
 228
 229 :Optional Parameters:
 230
 231     :git_tag: The tag string to sign and push to the Git repository.
 232        (default: the semantic version string)
 233
 234 The JSON schema for a PackageCloud release file appears below.
 235
 236 .. literalinclude:: ../../schema/release-packagecloud-schema.yaml
 237    :language: yaml
 238
 239
 240 Jenkins Jobs
 241 ------------
 242
 243 An example of a Jenkins job configuration that uses the global-jjb
 244 templates for maven and container release jobs appears next.
 245
 246 .. code-block:: none
 247
 248     - project:
 249         name: my-project-release
 250         project: my-project
 251         project-name: my-project
 252         build-node: centos7-docker-4c-4g
 253         mvn-settings: my-project-settings
 254         jobs:
 255             - '{project-name}-gerrit-release-jobs'
 256
 257
 258 .. note::
 259
 260    Release Engineers: please follow the setup guide below before adding the job definition.
 261
 262
 263 JJB Macros
 264 ----------
 265
 266 lf-release
 267 ~~~~~~~~~~
 268
 269 Release verify and merge jobs are the same except for their scm,
 270 trigger, and builders definition. This anchor is the common template.
 271
 272 JJB Templates
 273 -------------
 274
 275 Release Merge
 276 ~~~~~~~~~~~~~
 277
 278 This template supports Maven and Container release jobs.
 279
 280 :Template Name: {project-name}-release-merge
 281
 282 :Comment Trigger: remerge
 283
 284 :Required parameters:
 285
 286     :build-node: The node to run build on.
 287     :jenkins-ssh-release-credential: Credential to use for SSH. (Generally set
 288         in defaults.yaml)
 289     :project: Git repository name
 290     :project-name: Jenkins job name prefix
 291
 292 :Optional parameters:
 293
 294     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 295     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 296
 297     :gerrit_merge_triggers: Override Gerrit Triggers.
 298     :gerrit_trigger_file_paths: Override file paths filter which checks which
 299         file modifications will trigger a build.
 300         **default**::
 301
 302             - compare-type: REG_EXP
 303               pattern: '(releases\/.*\.yaml|\.releases\/.*\.yaml)'
 304
 305
 306 Release Verify
 307 ~~~~~~~~~~~~~~
 308
 309 This template supports Maven and Container release jobs.
 310
 311 :Template Name: {project-name}-release-verify
 312
 313 :Comment Trigger: recheck|reverify
 314
 315 :Required Parameters:
 316
 317     :build-node: The node to run build on.
 318     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 319         in defaults.yaml)
 320     :project: Git repository name
 321     :project-name: Jenkins job name prefix
 322
 323 :Optional Parameters:
 324
 325     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 326     :build-node: The node to run build on.
 327     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 328     :gerrit-skip-vote: Skip voting for this job. (default: false)
 329     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 330
 331     :gerrit_verify_triggers: Override Gerrit Triggers.
 332     :gerrit_trigger_file_paths: Override file paths filter which checks which
 333         file modifications will trigger a build.
 334         **default**::
 335
 336             - compare-type: REG_EXP
 337               pattern: '(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 :Template Names:
 351
 352     - {project-name}-pypi-release-merge
 353     - gerrit-pypi-release-merge
 354     - github-pypi-release-merge
 355
 356 :Comment Trigger: remerge
 357
 358 :Required Parameters:
 359
 360     :build-node: The node to run build on, which must be Centos.
 361     :jenkins-ssh-release-credential: Credential to use for SSH. (Generally set
 362         in defaults.yaml)
 363     :project: Git repository name
 364     :project-name: Jenkins job name prefix
 365
 366 :Optional Parameters:
 367
 368     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 369     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 370     :disable-job: Whether to disable the job (default: false)
 371     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 372     :pypi-stage-index: Base URL of the PyPI staging repository.
 373         (default https://test.pypi.org/simple)
 374     :pypi-repo: Key for the PyPI release repository in the .pypirc file,
 375         should be the repository pypy.org. (default: pypi)
 376     :use-release-file: Whether to use the release file. (default: true)
 377
 378     :gerrit_trigger_file_paths: Override file paths filter which checks which
 379         file modifications will trigger a build.
 380         **default**::
 381
 382             - compare-type: REG_EXP
 383               pattern: '(releases\/pypi.*\.yaml|\.releases\/pypi.*\.yaml)'
 384
 385 PyPI Release Verify
 386 ~~~~~~~~~~~~~~~~~~~
 387
 388 Verifies a Python package project on creation of a patch set with a
 389 release yaml file. Checks the contents of the release yaml file,
 390 checks the format of the version string, and downloads the release
 391 artifacts from the specified PyPI staging repository. The release
 392 verify template accepts neither a branch nor a stream parameter.
 393
 394 :Template Names:
 395
 396     - {project-name}-pypi-release-verify
 397     - gerrit-pypi-release-verify
 398     - github-pypi-release-verify
 399
 400 :Comment Trigger: recheck
 401
 402 :Required Parameters:
 403
 404     :build-node: The node to run build on, which must be Centos.
 405     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 406         in defaults.yaml)
 407     :project: Git repository name
 408     :project-name: Jenkins job name prefix
 409
 410 :Optional Parameters:
 411
 412     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 413     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 414     :disable-job: Whether to disable the job (default: false)
 415     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 416     :pypi-stage-index: Base URL of the PyPI staging repository.
 417         (default https://test.pypi.org/simple)
 418     :pypi-repo: Key for the PyPI release repository in the .pypirc file,
 419         should be the repository pypy.org (default: pypi)
 420     :use-release-file: Whether to use the release file. (default: true)
 421
 422     :gerrit_trigger_file_paths: Override file paths filter which checks which
 423         file modifications will trigger a build.
 424         **default**::
 425
 426             - compare-type: REG_EXP
 427               pattern: '(releases\/pypi.*\.yaml|\.releases\/pypi.*\.yaml)'
 428
 429 PackageCloud Release Verify
 430 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 431
 432 This template supports PackageCloud release jobs.
 433
 434 :Template Name: {project-name}-packagecloud-release-verify
 435
 436 :Comment Trigger: recheck|reverify
 437
 438 :Required Parameters:
 439
 440     :build-node: The node to run build on.
 441     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 442         in defaults.yaml)
 443     :project: Git repository name
 444     :project-name: Jenkins job name prefix
 445
 446 :Optional Parameters:
 447
 448     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 449     :build-node: The node to run build on.
 450     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 451     :gerrit-skip-vote: Skip voting for this job. (default: false)
 452     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 453
 454     :gerrit_verify_triggers: Override Gerrit Triggers.
 455     :gerrit_trigger_file_paths: Override file paths filter which checks which
 456         file modifications will trigger a build.
 457         **default**::
 458
 459             - compare-type: REG_EXP
 460               pattern: '(releases\/packagecloud.*\.yaml|\.releases\/packagecloud.*\.yaml)'
 461
 462
 463 PackageCloud Release Merge
 464 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 465
 466 This template supports PackageCloud release jobs.
 467
 468 :template name: {project-name}-packagecloud-release-merge
 469
 470 :comment trigger: remerge
 471
 472 :required parameters:
 473
 474     :build-node: the node to run build on.
 475     :jenkins-ssh-release-credential: credential to use for ssh. (generally set
 476         in defaults.yaml)
 477     :project: git repository name
 478     :project-name: jenkins job name prefix
 479
 480 :optional parameters:
 481
 482     :build-days-to-keep: days to keep build logs in jenkins. (default: 7)
 483     :build-timeout: timeout in minutes before aborting build. (default: 15)
 484
 485     :gerrit_merge_triggers: override gerrit triggers.
 486     :gerrit_trigger_file_paths: override file paths filter which checks which
 487         file modifications will trigger a build.
 488         **default**::
 489
 490             - compare-type: reg_exp
 491               pattern: '(releases\/packagecloud.*\.yaml|\.releases\/packagecloud.*\.yaml)'
 492
 493
 494 Setup for LFID, Nexus, Jenkins and Gerrit
 495 -----------------------------------------
 496
 497 This section is for the Linux Foundation release engineering team.
 498
 499 LFID
 500 ~~~~
 501
 502 Create an ``lfid`` and an ``ssh-key``
 503
 504 ``YOUR_RELEASE_USERNAME`` for example: onap-release
 505
 506 ``YOUR_RELEASE_EMAIL`` for example: collab-it+onap-release@linuxfoundation.org
 507
 508 ssh-key example:
 509
 510 .. code-block:: bash
 511
 512    ssh-keygen -t rsa -C "collab-it+odl-release@linuxfoundation.org"  -f /tmp/odl-release
 513
 514
 515 `Create an LFID with the above values <https://identity.linuxfoundation.org>`_
 516
 517
 518 Nexus
 519 ~~~~~
 520
 521 Create a Nexus account called ``'jenkins-release'`` with promote privileges.
 522
 523 .. image:: ../_static/nexus-promote-privs.png
 524
 525 Gerrit
 526 ~~~~~~
 527
 528 Log into your Gerrit with ``YOUR_RELEASE_USERNAME``, upload the public
 529 part of the ``ssh-key`` you created earlier. Log out of Gerrit and log
 530 in again with your normal account for the next steps.
 531
 532
 533 In Gerrit create a new group called ``self-serve-release`` and give it
 534 direct push rights via ``All-Projects`` Add ``YOUR_RELEASE_USERNAME``
 535 to group ``self-serve-release`` and group ``Non-Interactive Users``
 536
 537
 538 In All project, grant group self-serve-release the following:
 539
 540 .. code-block:: none
 541
 542     [access "refs/heads/*"]
 543       push = group self-serve-release
 544     [access "refs/tags/*"]
 545       createTag = group self-serve-release
 546       createSignedTag = group self-serve-release
 547       forgeCommitter = group self-serve-release
 548       push = group self-serve-release
 549
 550
 551 Jenkins
 552 ~~~~~~~
 553
 554 Add a global credential to Jenkins called ``jenkins-release`` and set
 555 the ID: ``'jenkins-release'`` as its value insert the private half of
 556 the ``ssh-key`` that you created for your Gerrit user.
 557
 558 Add Global variables in Jenkins:
 559 Jenkins configure -> Global properties -> Environment variables::
 560
 561     RELEASE_USERNAME = YOUR_RELEASE_USERNAME
 562     RELEASE_EMAIL = YOUR_RELEASE_EMAIL
 563
 564
 565 .. note::
 566
 567     Add these variables to your global-vars-$SILO.sh file or they will
 568     be overwritten.
 569
 570 Jenkins configure -> Managed Files -> Add a New Config -> Custom File
 571
 572 .. code-block:: none
 573
 574     id: signing-pubkey
 575     Name: SIGNING_PUBKEY (optional)
 576     Comment: SIGNING_PUBKEY (optional)
 577
 578     Content: (Ask Andy for the public signing key)
 579     -----BEGIN PGP PUBLIC KEY BLOCK-----
 580
 581
 582 Add or edit the managed file in Jenkins called ``lftoolsini``,
 583 appending a nexus section: Jenkins Settings -> Managed files -> Add
 584 (or edit) -> Custom file
 585
 586 .. code-block:: none
 587
 588    [nexus.example.com]
 589    username=jenkins-release
 590    password=<plaintext password>
 591
 592 Ci-management
 593 ~~~~~~~~~~~~~
 594
 595 Upgrade your project's global-jjb if needed, then add the following to
 596 your global defaults file (e.g., jjb/defaults.yaml).
 597
 598 .. code-block:: none
 599
 600    jenkins-ssh-release-credential: jenkins-release