Jenkins setup

jenkins-notes.md

Steps for setting up Jenkins/GitHub integration.

(This assumes some ability to manage Jenkins & use the command line.)

Steps done only once

Jenkins Server

Install Jenkins Plugins within Jenkins service

• Get the github plugin (which I believe brings in the git plugin)
• Get the embeddable-build-status plugin also to show build status badges in a readme.md file.

Logged onto machine running the Jenkins service

• Log into the server as the user that Jenkins runs under
• Set git user.name and user.email global config options.
• git config --global user.email JENKINS_USERNAME@WHATEVER_HOSTNAME
• git config --global user.name JENKINS_USERNAME
• This should match the GitHub machine user account username and email address used below

Generate rsa key pair on your Jenkins server

• Using command line, change directory to ~/.ssh
• Generate key with ssh-keygen -C "JENKINS_USERNAME@WHATEVER_HOSTNAME"
• Note that -C comment is optional, just helps you identify the public key later
• Do NOT use a passphrase for the keygen. Just hit enter twice.
• Copy contents of public key (~/.ssh/id_rsa.pub, for pasting later into github)

On GitHub

Create a new Machine User account in GitHub

• This is a separate user, just for use by Jenkins to interact with GitHub
• This will keep your identity separate from your Jenkins server
• Can be used for multiple repositories (as opposed to using a different deploy key which are repo specific)

Set up the GitHub Machine User Account for Jenkins

• Log into GitHub as the machine user
• Go to Settings -> SSH and GPG Keys
• Add a new SSH Key and paste in the contents of the public key from your server
• Use a meaningful title, like: Jenkins Build User or it's email address
• Then, back on the machine running jenkins, run ssh git@github.com and reply "yes" to add to known_host file

Back in Jenkins

Configure Jenkins GitHub plugin

• In Manage Jenkins -> Configure System:
• There is no need to add a GitHub server if using GitHub itself, as that's the default for the plugin
• Click the (?) icon next to the GitHub Servers section and copy the github-webhook URL you see there
• Set the global git user.name and user.email to match your global config options used before
• In Manage Jenkins -> Configure Global Security
• With Matix-based security, make sure the anonymous user has Job/ViewStatus (and only that) enabled. This is to allow the build badges to be viewed by anyone on GitHub.

Steps done once for each GitHub repository

In GitHub Configure Project to notify Jenkins

• Log into Github as the owner or collaborator of a repo
• Go to Settings -> Integrations & services
• Click on "Add service" for Jenkins and select 'Jenkins (Github plugin)'
• Add you github-webhook URL from above
• Check the 'Active' checkbox and then push "Update service"
• Take note of the "Test Service" button as this will be used later
• In the readme.md (or where ever you want the Jenkins build badge) add the line that looks something like [![Build Status](https://yourjenkins.com/buildStatus/icon?job=hello-world)](https://yourjenkins.com/job/hello-world/)
• More details are in the docs for the embeddable-build-status plugin

In Jenkins, configure job to work with GitHub

• In the general options, add the URL to the github project
• Under Source Code Management, select Git
• For the repository URL, enter the URL you'd use to git clone your project with
• For Credentials use 'jenkins' which corresponds to the id_rsa keypair generated earlier
• Under Build Triggers, check the "GitHub hook trigger for GITScm polling"
• Add other build tasks as needed for the job

Test the webhook

• Back in GitHub, in the Integrations & services for the repo, hit the "Test services" button.
• This should trigger a build in Jenkins.
• Test again with a commit/push or PR merge.