CI Jenkins library

Note

TL;DR - Amarula Solutions’ core CI Jenkins shared library (ci_scripts) — providing the Build, Verification, AndroidBuild, Archiva, Sftp, and Ui classes for standardized Git/repo project building, Gerrit verification, artifact deployment, and UI parameterization across all Jenkins pipelines. - Supports Docker-based builds, Mattermost/Teams notifications, and complete repo-managed project verification workflows.

CI Jenkins Library is shared library for Jenkins that helps with common operations and generic builders for specific tasks. It simplifies some common tasks that we do in our Jenkins jobs.

source: https://gitea.amarulasolutions.com/i-tools/ci_jenkins_lib

source: https://gerrit-review.amarulasolutions.com/admin/repos/i-tools/ci_jenkins_lib

configured as:

name: ci_scripts
load implicitly: true
allow default version to be overridden: true

How do you install the library?

Add the repository to your Jenkins instance as Shared library:

go to “Manage Jenkins” > “Configure System”
scroll down to “Global Pipeline Libraries” section
use “Add”
1. Name: ci_scripts
2. Default version: master
3. Retrieval method → Modern SCM
  1. Source Code Management → Git
  2. Project Repository: ssh://gitea@gitea.amarulasolutions.com:38745/i-tools/ci_jenkins_lib.git
“Save”

How do you configure it?

go to “Manage Jenkins” > “Configure System”
scroll down to “Global properties” section
use the “Environment variables” option
define these variables (values are examples):
- DOCKER_REGISTRY_HTTPS_URL : “https://registry.amarulasolutions.com:443”
- DOCKER_REGISTRY_USER : “amarulabot”
  - name of the credentials to use to authenticate with the registry
  - the credentials are of type Username with password
- GERRIT_HOST : “gerrit-review.amarulasolutions.com”
- GERRIT_USER_EMAIL : “amarulabot@amarulasolutions.com”
- GERRIT_USER_NAME : “amarulabot”
- JENKINS_GERRIT_REST_API_CREDENTIAL_ID : “jenkins_https@gerrit”
“Save”

Optional installation steps

Mattermost endpoint url

Set “MATTERMOST_ENDPOINT_URL” global variable in Jenkins in form: https://mattermost.amarulasolutions.com/hooks/abc

MS Teams endpoint url

Set “TEAMS_ENDPOINT” global variable in Jenkins in form: https://amarulasolutions.webhook.office.com/webhookb2/abc/IncomingWebhook/abc

Library description

Steps

notification.`monitoredStage`

The monitoredStage wraps regular stage step with a try-catch and can notify when build fails.

`notification.notifySuccess`

This step should be used to notify that the build finished successfully.

node() {
  notification.monitoredStage('Source sync') {
    // work
  }

  notification.monitoredStage('Build') {
    // work
  }

  notification.notifySuccess()
}

The notifications are sent to defined Mattermost and MS Teams endpoints and channels. Those are determined from the global environment variables: MATTERMOST_ENDPOINT_URL and TEAMS_ENDPOINT.

notification.`withMattermostEndpoint` / notification.`withTeamsEndpoint`

Allows to change the endpoints for notifications inside them.

def mattermostEndpoint = 'x'
def teamsEndpoint = 'y'

node() {
  notification.withMattermostEndpoint(mattermostEndpoint, 'channel name') {
  notification.withTeamsEndpoint(teamsEndpoint) {
  notification.monitoredStage('Source sync') {
    // work
  }

  notification.monitoredStage('Build') {
    // work
  }

  } // end withTeamsEndpoint
  } // end withMattermostEndpoint

  notification.notifySuccess()
}

Main classes

This is only a brief description of the classes. See the specific class page for more details.

com.amarula.build.Build

Helper class that generalizes builds of git and repo managed projects. It checks the environment for variables set by Gerrit trigger plugin and synces the change(s). It can be set whether to checkout or cherry-pick the changes.

com.amarula.build.AndroidBuild

Helper class derived from Build that generalizes Android OS code sync and build steps.

com.amarula.build.Verification

Helper class derived from Build that generalizes build verification of git and repo managed projects. It sends review to Gerrit to each change.

com.amarula.deploy.Archiva

The Archiva class provides methods for uploading files to the Archiva repository manager.

com.amarula.deploy.Sftp

This class handles common operations for uploading files to Sftp.

com.amarula.ui.Ui

This class is used to build parameters for a Jenkins job. It provides a builder pattern for adding various types of parameters to a job, such as boolean, string, choice, and password parameters.

Typical use

Repo project verification

The example below show typical use-case of repo project build verification. The pipeline fetches all relevant changes and sets a review to them.

Click here to see the example code …

import com.amarula.build.Verification

node {
  def dockerImage = 'system-x-builder:1.0'
  def manifestUrl = "${GITEA_SSH_URL}/myAndroidProject/manifest.git"
  def credentials = ['someCredentialId1', 'someCredentialId2']

  def options = [dockerImage : dockerImage]

  new Verification(this, env, credentials).repoBuild(manifestUrl, {
      sh 'make'
  }, options)
}

Repo project test build

The next example shows another typical use-case of test build with cherry-picking some changes.