isabella232 / leeroy

Jenkins integration with GitHub pull requests

Leeroy: Jenkins integration with GitHub pull requests

Leeroy is a Go application which integrates Jenkins with GitHub pull requests. Leeroy uses GitHub hooks to listen for pull request notifications and starts jobs on your Jenkins server. Using the Jenkins notification plugin, Leeroy updates the pull request using GitHub's status API with pending, success, failure, or error statuses.

This is based off the python project leeroy, but has a few custom updates to meet our needs, including custom build endpoint, DCO checking, issue labeling, etc.

Configuration

Leeroy needs to be configured to point to your GitHub repositories, to your Jenkins server and its jobs. You will need to add a GitHub webook pointing towards your leeroy instance at the endpoint /notification/github. You will also need to configure your Jenkins jobs to pull the right repositories and commits.

Leeroy Configuration

Below is a sample leeroy config file:

{
    "jenkins": {
        "username": "leeroy",
        "token": "YOUR_JENKINS_API_TOKEN",
        "base_url": "https://jenkins.dockerproject.com"
    },

    // Whether a Jenkins job is created for each commit in a pull request,
    // or only one for the last one.
    // What commits to build in a pull request. There are three options:
    // "all": build all commits in the pull request.
    // "last": build only the last commit in the pull request.
    // "new": build only commits that don't already have a commit status set.
    "build_commits": "last", // (default)

    "github_token": "YOUR_GITHUB_TOKEN",
    "github_user":  "GITHUB_USER_FOR_ABOVE_TOKEN",

    // A list of dicts containing configuration for each GitHub repository &
    // Jenkins job pair you want to join together.
    "builds": [
        {
            "github_repo": "docker/docker",
            "jenkins_job_name": "Docker-PRs",
            "context": "janky" // context to send to github for status (if you
            wanna stack em)
        }
    ],

    // Basic Auth for endoints
    "user": "USER",
    "pass": "PASS"
}

Jenkins Configuration

1. Install the Jenkins git plugin and notification plugin.

2. Create a Jenkins job. Under "Job Notifications", set a Notification Endpoint with protocol HTTP and the URL pointing to /notification/jenkins on your Leeroy server. If your Leeroy server is leeroy.example.com, set this to http://leeroy.example.com/notification/jenkins.

3. Check the "This build is parameterized" checkbox, and add 4 string parameters: GIT_BASE_REPO, GIT_HEAD_REPO, GIT_SHA1, and GITHUB_URL. Default values like username/repo for GIT_BASE_REPO and GIT_HEAD_REPO, and master for GIT_SHA1 are a good idea, but not required.

4. Under "Source Code Management", select Git. Set the "Repository URL" to [email protected]:$GIT_HEAD_REPO.git. Set "Branch Specifier" to $GIT_SHA1.

5. Configure the rest of the job however you would otherwise.

Usage

$ leeroy -h
Usage of leeroy:
  -cert="": path to ssl certificate
  -config="/etc/leeroy/config.json": path to config file
  -d=false: run in debug mode
  -key="": path to ssl key
  -port="80": port to use
  -v=false: print version and exit (shorthand)
  -version=false: print version and exit

License

MIT. See LICENSE file.