README.md

GPII Continuous Integration Service

The GPII Continuous Integration server uses Jenkins Job Builder definitions located in the jenkins_jobs directory of this repository to generate its configuration. This allows CI server jobs to be maintained transparently using version control instead of having to rely on the Jenkins UI.

The CI server is deployed on a CentOS VM. It delegates the majority of job tasks to physical hosts so that job performance issues don't affect the Jenkins process and also because certain jobs require VMs that can provide windowing environments. One exception is the update-jenkins-job-definitions job which runs on the CI server itself. This job should not be removed. The execution of the update-jenkins-job-definitions job can be checked as a usual build.

The remaining definitions in the jenkins_jobs directory are what the GPII build jobs use:

• defaults.yml - default values used by multiple jobs
• linux.yml - job definition for the GPII Linux Personalization Framework
• universal.yml - job defintion for the GPII Universal project
• windows.yml - job defintion for the GPII Windows Framework project

How CI Jobs Get Triggered

Pull requests sent by user accounts whitelisted in the macros.yml file will trigger builds in the CI environment using the GitHub Pull Request Builder plugin. The CI server checks for PR changes every five minutes.

Triggered CI jobs report their results as PR comments. Results will usually state whether a job passed or failed.

How to Avoid Triggering a Job

If you would like to avoid triggering a job please include the following text in your PR comment:

[skip ci]

How to Manually Trigger a Job

If an unrecognized account is used to send a PR then the CI server will post a comment for that PR asking an administrator to verify changes and trigger the job. An administrator can trigger jobs by posting the following comment:

ok to test

A list of administrators named admin-list is maintained in the macros.yml file.

How Can Repositories Use This Service?

The CI server uses the gpii-bot account to post PR comments. It has to be added as a collaborator, with push access, to every repository that needs to be integrated with the CI service.

Where can I find help about how to define jobs

The first place to look at is the Jenkins Job Builder documentation.

The fixtures directory which can be found in each JJB module tests is another useful resource of sample definitions.