DRAFT - Jenkins integrations
This page is work-in-progress.
Introduction
This document describes how the Jenkins server has been configured in terms of integrations to other systems.
Jenkins-GitHub integration
Jenkins has been set up with add-ons for integrating with GitHub and repositories in the UnionVMS organisation. In particular, it has been configured to build open pull requests and report back to GitHub whether the pull request can be merged.
GitHub Pull Request Builder - Configuration
For general information and other configuration options regarding this plugin, please refer to the plugin homepage or GitHub project page.
This plugin is configured to build pull requests that are opened against repositories within the UnionVMS organisation. Each repository needs to be configured separately and the below table shows the currently configured repositories.
| Repository name | Jenkins job | Target branch | Executing GitHub user | Whitelisted users |
|---|---|---|---|---|
| UVMS-TEST-REPO | UVMS-TEST-REPO-Pull-Requests | development | FOCUSBOT | Users that are part of the UnionVMS organisation |
The plugin is configured globally, i.e. in the Jenkins system settings, and per job. The job configuration can complement some of the global configurations.
Global configuration items of importance are listed below. The rest of the global configuration items have been left at their default values.
| Global configuration item | Value |
|---|---|
| GitHub Server API URL | https://api.github.com |
| Jenkins URL override | Not set |
| Shared secret | Not set |
| Credentials | https://api.github.com GitHub auto generated token credentials |
| Auto-manage webhooks | Checked |
Note: The global configuration allows setting default values for scheduling, administrators, build trigger messages. These default values are then used within the job configurations. It could be worth adding administrators here.
A typical job configuration can be found in the configuration of UVMS-TEST-REPO-Pull-Requests.
| Job configuration item | Value |
|---|---|
| General section | |
| GitHub Project | URL to the project in GitHub, e.g. https://github.com/UnionVMS/UVMS-TEST-REPO/ |
| Source Code Management section | |
| Git | Selected |
| Repository URL | The URL to the repository as written in a git clone command, e.g. https://github.com/UnionVMS/UVMS-TEST-REPO.git |
| Credentials | The GitHub user credentials, i.e. the ones specified for general GitHub access, not the API-tokens defined as part of the global configuration of the GitHub Pull Request Builder plugin |
| Name (under advanced) | origin |
| Refspec (under advanced) | +refs/pull/*:refs/remotes/origin/pr/* (to also build branches, change to +refs/heads/*:refs/remotes/origin/* +refs/pull/*:refs/remotes/origin/pr/*) |
| Branches to build | ${sha1} |
| Build Triggers section | |
| GitHub Pull Request Builder | Selected |
| GitHub API credentials | Select one of those defined in the global configuration, e.g. "https://api.github.com GitHub auto generated token credentials" |
| Crontab Line (under advanced) | The polling interval. For instance, for every third minute, set to H/3 * * * *. Note that it is recommended to configure a web-hook instead of using polling. |
| Whitelist (under advanced) | uvms List of users whose pull requests are allowed to be built without the confirmation of an admin. |
| List of organizations (under advanced) | UnionVMS Organisations whose members should be automatically whitelisted. |
| Post-build Actions section | |
| Set GitHub commit status (universal) | Selected |
| Commit SHA | Latest build revision |
| Repositories | Any defined in job repository |
| Commit context | From GitHub property with fallback to job name |
| Status result | Based on build result manually defined |
| Status backref | Backref to the build |
GitHub Pull Request Builder - Everyday work
The pull request builder jobs have been configured to listen for pull request changes in GitHub. If the job succeeds, then the pull request information will be updated in GitHub. Note that the current configuration does not require the pull request to have successful builds associated with it in order for a user to merge the pull request. This can be configured in GitHub. During the build, the pull request will indicate that there is a build pending.
Build pending:
Build completed successfully:
Build details (the Details-link is a link to the build in Jenkins):
The jobs can also be configured so that they can be manually triggered from Jenkins or from GitHub.
To manually trigger from Jenkins, the job must first be configured as a parameterized job that takes a string parameter named sha1. Set the default value of the parameter to the default branch.
When triggering, enter the commit hash or the pull request refname as value for this parameter. E.g.:
It is however even easier to trigger the build manually from within GitHub, and more specifically from within the open merge request. To do this, simply add a comment saying "test this please":
If a GitHub user is not whitelisted in Jenkins, Jenkins will post a comment to the pull request in GitHub asking a whitelisted user to accept the pull request for build. Without this check, any user could open a pull request against the repository and this way have Jenkins executing their potentially harmful code.