Jenkins and GitHub integration

Overview

GitHub and Jenkins integration allows build status to be attached to a commit and viewed at GitHub. Jenkins build can be triggered by a push to an existing branch, creation of new branch or new pull request.

NOTE: this description is valid as of Jenkins version Jenkins ver. 2.107.2 and should be revised at Jenkins update.

GitHub setup

1. Create a new worker user at GitHub.

This user will be used by Jenkins for checking out repositories and pushing commit's build status to GitHub. Note: for IIS this user is openaire-devs.

2. Generate a Personal Access Token for the worker user with repo:status access scope.

Personal Access Token can be created using this document.

3. Add worker user as a collaborator to project with Admin permission level.

Jenkins build configuration for IIS

IIS is build with JDK and Maven. To build IIS we should create a Jenkins managed file with configuration of Maven and JDK as Jenkins tools.

1. Create a managed file of type Custom file.
2. Populate the file with the following properties:

MAVEN_VERSION="<maven tool version>"` # the name of maven tool as configured in Jenkins
JDK_VERSION="<jdk tool version>"` # the name of JDK tool as configured in Jenkins  

Note: to create a managed file Jenkins user must have sufficient privileges.

Jenkins credentials setup

1. Create a credential entry of type/kind: Username with password with GitHub's worker user as username and worker user's Personal Access Token as the password. The credentials should be scoped at a level accessible for project's build configuration i.e. system or project.

Note: the type/kind of credentials is forced by GitHub Branch Source Plugin for Jenkins which supports only this type/kind of credentials.

Jenkins job setup

To setup a Jenkins job we must make sure that there is a Jenkinsfile checked in the project. This file will be used to create a build configuration in Jenkins and should contain project build and test instructions.

1. Create a new Jenkins build configuration using Multibranch Pipeline template.

Select GitHub as the branch sources and use the credentials for the worker user. This also allows to bypass GitHub's rate limit of 60 requests per hour, increasing this number to 5000 requests.

2. In Build Configuration select by Jenkinsfile and set the path to Jenkinsfil within the repository: Jenkinsfile.
3. Optionally configure other properties of the job, for example build triggers.