X-Git-Url: https://gerrit.linuxfoundation.org/infra/gitweb?a=blobdiff_plain;f=docs%2Fjjb%2Flf-release-jobs.rst;h=562dcef07cbfb74034c1511813ea07a6df6ceaa9;hb=027277490bf761405dcc4cbb02c4c92874d58766;hp=73187b13580ac18d65d1a734e187ba777a562306;hpb=414d5ad24254661a0c49971e75c57e24dce0f88c;p=releng%2Fglobal-jjb.git diff --git a/docs/jjb/lf-release-jobs.rst b/docs/jjb/lf-release-jobs.rst index 73187b13..562dcef0 100644 --- a/docs/jjb/lf-release-jobs.rst +++ b/docs/jjb/lf-release-jobs.rst @@ -1,79 +1,109 @@ .. _lf-global-jjb-release: ####################### -Self Serve Release Jobs +Self-Serve Release Jobs ####################### -Self serve release jobs allow a project to create a releases directory and then place a release file in it. -Jenkins will pick this up and then promote the artifact from the staging log directory (log_dir) and tag the release -with the defined version. maven_central_url is optional +Self-serve release jobs allow a project team to direct Jenkins to +promote a jar file or container image from a staging area to a release +area. To trigger the action, create a releases/ or .releases/ +directory, add a release yaml file to it, and submit a change set with +exactly one release yaml file to Gerrit. Upon merge of the change, +Jenkins will sign the reference extrapolated by log_dir and promote +the artifact. The expected format of the release yaml file is shown in +examples below. + +The build node for maven and container release jobs must be CentOS, +which supports the sigul client for accessing a signing server. The +build node for container release jobs must have Docker installed. + +A release job can also be triggered from Jenkins via the "Build with +parameters" action, removing the need for a release yaml file. The +parameters must be filled out in the same way as a release yaml file, +except for the special USE_RELEASE_FILE and DRY_RUN check boxes. The +USE_RELEASE_FILE check box must be unchecked if the job is expected to +run with a release file, while passing the required information as +build parameters. Similarly, the DRY_RUN check box must be unchecked +if the job needs to be tested while skipping repository promotion to +Nexus. + +The special parameters are as follows:: + + GERRIT_BRANCH = master + VERSION = 1.0.0 + LOG_DIR = example-project-maven-stage-master/17/ + DISTRIBUTION_TYPE = maven + USE_RELEASE_FILE = false + DRY_RUN = false .. note:: - Example of a project's release file: + The release file regex is: (releases\/.*\.yaml|\.releases\/.*\.yaml). + In words, the directory name can be ".releases" or "releases"; the file + name can be anything with suffix ".yaml". + +Example of a maven release file: .. code-block:: bash - $ cat releases/1.0.0.yaml - --- - distribution_type: 'maven' - version: '1.0.0' - project: 'example-test-release' - log_dir: 'example-test-release-maven-stage-master/17/' - maven_central_url: 'oss.sonatype.org' + $ cat releases/1.0.0-maven.yaml + --- + distribution_type: 'maven' + version: '1.0.0' + project: 'example-project' + log_dir: 'example-project-maven-stage-master/17/' -.. note:: - Example of a terse Jenkins job to call global-jjb macro: +An example of a container release file appears below. The first +version string is applied to all released containers. The +per-container version strings are used to pull images from the +container registry. -.. code-block:: none +.. code-block:: bash - - project: - name: '{project-name}-gerrit-release-jobs' - project: 'example-test-release' - build-node: centos7-builder-2c-1g - project-name: example-test-release - jobs: - - '{project-name}-gerrit-release-jobs' + $ cat releases/1.0.0-container.yaml + --- + distribution_type: 'container' + version: '1.0.0' + project: 'test' + containers: + - name: test-backend + version: 1.0.0-20190806T184921Z + - name: test-frontend + version: 1.0.0-20190806T184921Z -.. note:: - Example of a verbose Jenkins job to call global-jjb macro: +.. note:: -.. code-block:: none + Job should be appended under gerrit-maven-stage - - project: - name: '{project-name}-releases-verify' - project: 'example-test-release' - build-node: centos7-builder-2c-1g - project-name: example-test-release - jobs: - - 'gerrit-releases-verify' +Example of a terse Jenkins job to call the global-jjb macro: .. code-block:: none - - project: - name: '{project-name}-releases-merge' - project: 'example-test-release' - build-node: centos7-builder-2c-1g - project-name: example-test-release - jobs: - - 'gerrit-releases-merge' + - gerrit-maven-stage: + sign-artifacts: true + build-node: centos7-docker-8c-8g + maven-versions-plugin: true + - '{project-name}-gerrit-release-jobs': + build-node: centos7-docker-8c-8g .. note:: - Release Engineers Please follow the setup guide before adding the job definition: + Release Engineers: please follow the setup guide below before adding the job definition. + -Setup for LFID Nexus Jenkins and Gerrit: -======================================== +Setup for LFID, Nexus, Jenkins and Gerrit +========================================= LFID ==== Create an ``lfid`` and an ``ssh-key`` -``RELEASE_USERNAME`` -``RELEASE_EMAIL`` +``YOUR_RELEASE_USERNAME`` for example: onap-release + +``YOUR_RELEASE_EMAIL`` for example: collab-it+onap-release@linuxfoundation.org ssh-key example: @@ -82,7 +112,8 @@ ssh-key example: ssh-keygen -t rsa -C "collab-it+odl-release@linuxfoundation.org" -f /tmp/odl-release -`Create an LFID `_ +`Create an LFID with the above values `_ + Nexus ===== @@ -94,44 +125,67 @@ Create a Nexus account called ``'jenkins-release'`` with promote privileges. Gerrit ====== -Log into your Gerrit with ``RELEASE_USERNAME``, upload the ``ssh-key`` you created earlier. -Log out of Gerrit and log in again with your normal account for the next steps. +Log into your Gerrit with ``YOUR_RELEASE_USERNAME``, upload the public +part of the ``ssh-key`` you created earlier. Log out of Gerrit and log +in again with your normal account for the next steps. + + +In Gerrit create a new group called ``self-serve-release`` and give it +direct push rights via ``All-Projects`` Add ``YOUR_RELEASE_USERNAME`` +to group ``self-serve-release`` and group ``Non-Interactive Users`` -In Gerrit create a new group called ``self-serve-release`` and give it direct push rights via ``All-Projects`` -``push - refs/heads/*`` -1. Add a push reference -2. Set the ref as refs/heads/* -3. Make sure "force push" is not checked +In All project, grant group self-serve-release the following: + +.. code-block:: none + + [access "refs/heads/*"] + push = group self-serve-release + [access "refs/tags/*"] + createTag = group self-serve-release + createSignedTag = group self-serve-release + forgeCommitter = group self-serve-release + push = group self-serve-release -Add ``RELEASE_USERNAME`` to group ``self-serve-release`` and group ``Non-Interactive Users`` Jenkins ======= -Add a global credential to Jenkins called ``jenkins-release`` and set the ID: ``'jenkins-release'`` -as its value insert the ``ssh-key`` that you uploaded to Gerrit. +Add a global credential to Jenkins called ``jenkins-release`` and set +the ID: ``'jenkins-release'`` as its value insert the private half of +the ``ssh-key`` that you created for your Gerrit user. Add Global vars in Jenkins: -Jenkins configre -> Global properties -> Environment variables +Jenkins configure -> Global properties -> Environment variables -``RELEASE_USERNAME = $RELEASE_USERNAME`` -``RELEASE_EMAIL = $RELEASE_EMAIL`` +``RELEASE_USERNAME = YOUR_RELEASE_USERNAME`` +``RELEASE_EMAIL = YOUR_RELEASE_EMAIL`` -Add or edit the managed file in Jenkins called ``lftoolsini``, appending a nexus section: -Jenkins Settings -> Managed files -> Add (or edit) -> Custom file +Jenkins configure -> Managed Files -> Add a New Config -> Custom File + +id: signing-pubkey +Name: SIGNING_PUBKEY (optional) +Comment: SIGNING_PUBKEY (optional) + +Content: (Ask Andy for the public signing key) +-----BEGIN PGP PUBLIC KEY BLOCK----- + + +Add or edit the managed file in Jenkins called ``lftoolsini``, +appending a nexus section: Jenkins Settings -> Managed files -> Add +(or edit) -> Custom file .. code-block:: none - [nexus] + [nexus.example.com] username=jenkins-release - password=redacted + password= Ci-management ============= -upgrade you projects global-jjb if needed -add this to your global defaults file (eg: jjb/defaults.yaml) +Upgrade your project's global-jjb if needed, then add the following to +your global defaults file (e.g., jjb/defaults.yaml). .. code-block:: bash @@ -143,8 +197,8 @@ Macros lf-release ---------- -Release verify and merge jobs are the same except for their scm, trigger, and -builders definition. This anchor is the common template. +Release verify and merge jobs are the same except for their scm, +trigger, and builders definition. This anchor is the common template. Job Templates ============= @@ -152,21 +206,7 @@ Job Templates Release Merge ------------- -Runs: - -- sigul-install -- sigul-configuration -- checkout ref from taglist.log -- applies the $PROJECT.bundle -- signs, tags and pushes - -.. code-block:: bash - - lftools nexus release --server $NEXUS_URL $STAGING_REPO - - -:Template Name: - - {project-name}-release-merge-{stream} +:Template Name: {project-name}-release-merge :Comment Trigger: remerge @@ -175,11 +215,11 @@ Runs: :build-node: The node to run build on. :jenkins-ssh-release-credential: Credential to use for SSH. (Generally set in defaults.yaml) - :stream: run this job against: master + :stream: run this job against: ** :Optional parameters: - :branch: Git branch to fetch for the build. (default: master) + :branch: Git branch to fetch for the build. (default: all) :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7) :build-timeout: Timeout in minutes before aborting build. (default: 15) :project-pattern: Project to trigger build against. (default: \*\*) @@ -189,38 +229,27 @@ Runs: file modifications will trigger a build. **default**:: - - compare-type: ANT - pattern: 'releases/*.yaml' + - compare-type: REG_EXP + pattern: '(releases\/.*\.yaml|\.releases\/.*\.yaml)' Release Verify ------------------ -Release verify job checks the schema and ensures that the staging-repo.txt.gz -is available on the job. - -- sigul-install -- sigul-configuration -- checkout ref from taglist.log -- applies the $PROJECT.bundle -- signs and shows signature - - -:Template Names: - - {project-name}-release-verify-{stream} +:Template Name: {project-name}-release-verify :Comment Trigger: recheck|reverify :Required Parameters: :build-node: The node to run build on. - :jenkins-ssh-release-credential: Credential to use for SSH. (Generally set + :jenkins-ssh-credential: Credential to use for SSH. (Generally set in defaults.yaml) - :stream: run this job against: master + :stream: run this job against: ** :Optional Parameters: - :branch: Git branch to fetch for the build. (default: master) + :branch: Git branch to fetch for the build. (default: all) :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7) :build-node: The node to run build on. :build-timeout: Timeout in minutes before aborting build. (default: 15) @@ -235,5 +264,5 @@ is available on the job. file modifications will trigger a build. **default**:: - - compare-type: ANT - pattern: 'releases/*.yaml' + - compare-type: REG_EXP + pattern: '(releases\/.*\.yaml|\.releases\/.*\.yaml)'