CI Jenkins library

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

Installation

Add the repository to your Jenkins instance as Shared library:

  1. go to “Manage Jenkins” > “Configure System”

  2. scroll down to “Global Pipeline Libraries” section

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

  4. “Save”

Set configuration variables

  1. go to “Manage Jenkins” > “Configure System”

  2. scroll down to “Global properties” section

  3. use the “Environment variables” option

  4. define these variables (values are examples):

  5. “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.

 Click here to see the example code …

import com.amarula.build.Build

node {
  def dockerImage = 'system-x-builder:1.0'
  def credentials = ['someCredentialId1', 'someCredentialId2']

  Build systemXBuild = new Build(this, env, credentials)
  systemXBuild.setSyncMethod(Build.CHERRYPICK)
  systemXBuild.repoBuild("${GITEA_SSH_URL}/myAndroidProject/manifest.git", {
      sh 'make'
  }, [dockerImage: dockerImage,
      gerritMultitopic: true])
}

Contents: