Global Macros¶

The purpose of writing global macros is use across the repositories and reduce the redundant code. These macros are easy to manage.

SCM¶

The scm module allows referencing multiple repositories in a Jenkins job

gerrit-trigger-scm

This macro is used to get the GERRIT_REFSPEC on every freestyle verify job. Below are the required and optional parameters for this macro. This macro is used to get the GERRIT_REFSPEC of the patchset on top of the parent commit of the patchset.

Required Parameters:

base-dir: $BASE_DIR$ (gopath/src/github.com/hyperledger/$PROJECT) or specify the directory path to clone the repository.

Optional Parameters:

GERRIT_BRANCH - Gerrit_branch is a jenkins environment variable contains the branch name to build against GERRIT_REFSPEC - RefSpec number ex: refs/changes/32/30032/1

gerrit-trigger-scm-merge

This macro is used to get the GERRIT_REFSPEC on every freestyle merge job. Below are the required and optional parameters for this macro. This macro is used to get the latest commit from the repository instead of GERRIT_REFSPEC of the patchset.

Required Parameters:

base-dir: $BASE_DIR (gopath/src/github.com/hyperledger/$PROJECT) or specify the directory path to clone
the repository.

 **Optional Parameters:**

 GERRIT_BRANCH - Gerrit_branch is a jenkins environment variable contains the branch name to build against
 GERRIT_REFSPEC - RefSpec number ex: refs/changes/32/30032/1 (default: blank)

 When manually building the job, replace the GERRIT_REFSPEC parameter with the Gerrit patchset
 reference number of the patch. You can specify the GERRIT_BRANCH to test specific changes

## Wrappers

Wrappers can alter the way the build is run as well as the build output.

build-timeout

This wrapper is used to set the build timeout in freestyle jobs.
```
wrappers:
  - build-timeout:
      timeout: '{build_timeout}'
```
See example here https://github.com/hyperledger/ci-management/blob/master/jjb/fabric-sdk-py/fabric-sdk-py-jobs.yaml

Required Parameters:
- timeout: Set timeout in mins from job configuration. ex: build_timeout: 50

hyperledger-infra-wrappers

This wrapper is required for all jobs as it configures the wrappers needed by all Hyperledger infra. This sets the timestamps, mask-passwords, openstack: single-use: true and set ssh-agent-credentials user to hyperledger-jobbuilder
```
wrappers:
  - hyperledger-infra-wrappers
```

Triggers¶

Triggers define what causes a Jenkins job to start building.

gerrit-trigger-patch-submitted

This macro will trigger the Jenkins jobs when a patchset is created.

This macro triggers a jenkins job when a change-merged-event is triggered It won’t trigger the job when a commit message is updated in the gerrit patchset. Triggers the jobs when a comment is posted in the gerrit patchset. Comments are specified in the job configuration. It triggers the job on a branch pattren specified in the job configuration.
```
triggers:
  - gerrit-trigger-patch-submitted:
      name: '{project}'
      branch: 'master'
      trigger-comment1: 'reverify-x$'
      trigger-comment2: 'reverify$'
```
Required Parameters:

project: Provide project name from the job configuration.

gerrit-trigger-patch-merged

This macro will trigger the Jenkins jobs when a patchset is merged.

Required Parameters:

name: Project Name ex: fabric or $PROJECT environment variable

branch: Provide the branch name. Provide blank value if you would like trigger jon on any branch.

Sample job configuration. See this example https://github.com/hyperledger/ci-management/blob/master/jjb/fabric-sdk-java/fabric-sdk-java-jobs.yaml

::

triggers:

gerrit-trigger-patch-merged: name: ‘{project}’

branch: ‘’

gerrit-comment-trigger

This macro is used to trigger builds based on the comment provided in the gerrit patchset. Meaning when you use this macro in a job configuration, this won’t trigger a job until you post a comment in gerrit patchset to trigger a job. Also, this macro skips the gerrit vote for any build result.
```
triggers:
  - gerrit-comment-trigger:
      name: '{project}'
      branch: ''
      trigger-comment: 'Run UnitTest'
```
Required Parameters:

name: Project Name ex: fabric

branch: Provide the branch name. Provide blank value if you would like trigger jon on any branch.

trigger-comment: Provide the comment for which you would like to trigger the job.

gerrit-trigger-tag

This macro will trigger the Jenkins jobs when a tag is created.
```
triggers:
  - gerrit-trigger-tag:
      name: '{project}'
      branch: 'master'
```
Required Parameters:

name: Project Name ex: fabric

branch: Provide the branch name. Provide blank value if you would like trigger jon on any branch.

Publishers:¶

Publishers define actions that the Jenkins job should perform after the build is complete.

log-artifacts

This macro is used to collects the log files with extension .log and keep it in the WORKSPACE directory. Also, this macro won’t fail the build if .log files are missing in the build.
```
publishers:
  - log-artifacts
```

archive-artifacts

This macro is used to publish the artifacts provided in the on the jenkins console.
```
publishers:
  - archive-artifacts:
      artifacts: '.tox/**/*.log'
```
The above macro archives the .log files and display on the jenkins console.

code-coverage-report

This macro is used to read the report-file and publish the cobuertura code coverage report on the Jenkins job console. The threshold limit is hard coded in this macro. Please refer the macro for more details on the threshold limit.
```
publishers:
  - code-coverage-report
```

test-logs

This macro is used to collects the artifacts **/*.csv, **/*.log, **/*.xml and archive on the jenkins build artifacts section.
```
publishers:
  - test-logs
```

fabric-email-notification

This macro is used to publish the build notifications through email to the list of email-ids sp
```
publishers:
  - fabric-email-notification:
      email-ids: 'foo@gmail.com''
      output_format: ''
      developer-email: 'developers'
```
Required Parameters:

email-ids: Provide the email-ids list here to send the email notification to. output_format: provide the log file type

## Builders

Builders define actions that the Jenkins job should execute

provide-maven-settings

This macro is used to provide the configuration files.
```
builders:
  - provide-maven-settings:
      global-settings-file: 'global-settings'
      fabric-settings-file: '{mvn-settings}'
```
Required Parameters:

mvn-settings: provide the value to this variable. Each project has it’s own maven-settings file. See example here mvn-settings: 'fabric-ca-settings' if it fabric, pass fabric-settings to maven-settings variable.

docker-login (Dependent on provide-maven-settings macro)

This macro is used to perform docker login with nexus credentials to publish images to nexus3.

golang-environment-x86_64

This macro is used to set gopath and goroot for any go related projects on x86_64 build nodes. This macro reads the GO_VER value from the ci.properties files listed in fabric, fabric-ca repository and provide the same to the properties-content.
```
builders:
  - 'golang-environment-{arch}'
```
Same applicable to any arch (s390x or ppc64le)

output-environment

Display the details of the Jenkins build environment on the Jenkins console
```
builders:
  - output-environment
```

clean-environment

This macro is used to clean the environment includes deleting containers, images (ignoring specific images and tags) and all the left over build artifacts before start the build.
```
builders:
  - clean-environment
```