Self-Serve Release Jobs¶

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 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 appears in schemas and 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 Jenkins user can also trigger a release job via the “Build with parameters” action, removing the need for a release yaml file. The user must enter parameters in the same way as a release yaml file, except for the special USE_RELEASE_FILE and DRY_RUN check boxes. The user must uncheck the USE_RELEASE_FILE check box if the job should run with a release file, while passing the required information as build parameters. Similarly, the user must uncheck the DRY_RUN check box to test the job 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

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”.

The JSON schema for a maven release job appears below.

---
$schema: "http://json-schema.org/schema#"
$id: "https://github.com/lfit/releng-global-jjb/blob/master/release-schema.yaml"

required:
  - "distribution_type"
  - "log_dir"
  - "project"
  - "version"

properties:
  distribution_type:
    type: "string"
  log_dir:
    type: "string"
  project:
    type: "string"
  version:
    type: "string"

Example of a maven release file:

$ 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/'

The JSON schema for a container release job appears below.

---
$schema: "http://json-schema.org/schema#"
$id: "https://github.com/lfit/releng-global-jjb/blob/master/release-container-schema.yaml"

required:
  - "containers"
  - "distribution_type"
  - "project"
  - "container_release_tag"
  - "ref"

properties:
  containers:
    type: "array"
    properties:
      name:
        type: "string"
      version:
        type: "string"
    additionalProperties: false
  distribution_type:
    type: "string"
  project:
    type: "string"
  container_release_tag:
    type: "string"
  container_pull_registry"
    type: "string"
  container_push_registry"
    type: "string"
  ref:
    type: "string"

An example of a container release file appears below. The job applies the container_release_tag string to all released containers. The job uses the per-container version strings to pull images from the container registry.

$ cat releases/1.0.0-container.yaml
---
distribution_type: 'container'
container_release_tag: '1.0.0'
container_pull_registry: 'nexus.onap.org:10003"
container_push_registry: 'nexus.onap.org:10002"
project: 'test'
containers:
    - name: test-backend
      version: 1.0.0-20190806T184921Z
    - name: test-frontend
      version: 1.0.0-20190806T184921Z

Note

Job should appear under gerrit-maven-stage

Example of a terse Jenkins job to call the global-jjb macro:

- 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 below before adding the job definition.

Setup for LFID, Nexus, Jenkins and Gerrit¶

LFID¶

Create an lfid and an ssh-key

YOUR_RELEASE_USERNAME for example: onap-release

YOUR_RELEASE_EMAIL for example: collab-it+onap-release@linuxfoundation.org

ssh-key example:

ssh-keygen -t rsa -C "collab-it+odl-release@linuxfoundation.org"  -f /tmp/odl-release

Create an LFID with the above values

Nexus¶

Create a Nexus account called 'jenkins-release' with promote privileges.

Gerrit¶

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 All project, grant group self-serve-release the following:

[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

Jenkins¶

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 configure -> Global properties -> Environment variables

RELEASE_USERNAME = YOUR_RELEASE_USERNAME RELEASE_EMAIL = YOUR_RELEASE_EMAIL

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

[nexus.example.com]
username=jenkins-release
password=<plaintext password>

Ci-management¶

Upgrade your project’s global-jjb if needed, then add the following to your global defaults file (e.g., jjb/defaults.yaml).

jenkins-ssh-release-credential: 'jenkins-release'

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.

Job Templates¶

Release Merge¶

Template Name:

{project-name}-release-merge

Comment Trigger:

remerge

Required parameters:

jenkins-ssh-release-credential:
build-node:	The node to run build on.
	Credential to use for SSH. (Generally set in defaults.yaml)
stream:	run this job against: **

Optional parameters:

build-days-to-keep:
branch:	Git branch to fetch for the build. (default: all)
	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: **)
gerrit_merge_triggers:
	Override Gerrit Triggers.
gerrit_trigger_file_paths:
	Override file paths filter which checks which file modifications will trigger a build. default: - compare-type: REG_EXP pattern: '(releases\/.\.yaml\|\.releases\/.\.yaml)'

Release Verify¶

Template Name:

{project-name}-release-verify

Comment Trigger:

recheck|reverify

Required Parameters:

jenkins-ssh-credential:
build-node:	The node to run build on.
	Credential to use for SSH. (Generally set in defaults.yaml)
stream:	run this job against: **

Optional Parameters:

build-days-to-keep:
branch:	Git branch to fetch for the build. (default: all)
	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)
doc-dir:	Directory where tox will place built docs. as defined in the tox.ini (default: docs/_build/html)
gerrit-skip-vote:
	Skip voting for this job. (default: false)
git-url:	URL clone project from. (default: $GIT_URL/$PROJECT)
project-pattern:
	Project to trigger build against. (default: **)
gerrit_verify_triggers:
	Override Gerrit Triggers.
gerrit_trigger_file_paths:
	Override file paths filter which checks which file modifications will trigger a build. default: - compare-type: REG_EXP pattern: '(releases\/.\.yaml\|\.releases\/.\.yaml)'