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