Repository files navigation

Trigger Jenkins Jobs via GitHub Webhooks and provide Webhook Payload Information as Environment Variables inside your Job.

This plugin is made by codeclou. We loveGitHub andJenkins.

• (1) Install the Pipeline plugins via thePipeline Bundle.
• (2) Download:github-webhook-notifier-plugin-1.2.0.hpi.zip and install the plugin.
• (3) In Jenkins global configuration define a "Webhook Secret" (see below)
• (4) Create a job called{gitHubRepoOwner}---{repoName} like e.g.codeclou---myapp
• (5) Configure a GitHub Webhook for push event. (see below)
• (6) Push a code change and job should be triggered

If you can agree with all statements, then this is for you.

• Bash is love. Bash is live.
• Using thegit commandline client in Jenkins Jobs:
  • gives me the control I want and need.
  • replaces all other mostly defunct and/or bloated Git Plugins.
• I only use GitHub.com for my repositories.
• I only 'git clone' viahttps:// URLs.
• I work with git branches and tags.
• I want my Jenkins jobs triggered at every push (branch or tag).
• I want my Jenkins jobs triggered exclusively via GitHub Webhook Push Events.
• I use Linux to run Jenkins.
• I want my Jenkins jobs triggered automatically by convention over configuration job naming.

Ok. Still here?! Then this might be for you

• Plugin REST Endpoint parses the actual GitHub Webhook JSON Payload and extracts its information.
• It then triggers all Jenkins jobs matching{repositoryOwner}---{repositoryName}.*
• Lastly it injects Environment Variables into the job run for you to determine what branch and revision is to clone.

This is how you need to configure the GitHub Webhook in your repository 'Settings'.

• Payload URL
  • https://jenkins/github-webhook-build-trigger/receive
  • Note:
    • The endpoint can be called without authentication.
• Content type
  • application/json
• Secret
  • Choose a good secret, at best a random sha512 hash. Use that secret for all webhooks of all your repositories.
• Which events ...
  • Just thepush event

You can configure theWebhook Secret Globally via 'Manage Jenkins' → 'Configure System' → 'Github Webhook Notifier Plugin'. If you do not configure it, HTTP 500 will be the response from the API.

Concerning 'Manage Jenkins' →'Configure Global Security', 'Prevent Cross Site Request Forgery exploits' can be enabled (the plugin will still work).When using matrix-based security 'Anonymous' needs 'Job' →build,discover,read permissions.

Configure your Jenkins Job like this so that it gets triggered by the Webhook events.

First of all thenaming conventions is{repositoryOwner}---{repositoryName}.*.That means if your repository ishttps://github.com/codeclou/test-webhook.git then your job must be calledcodeclou---test-webhook. You can have multiple jobs if you want for example a job that handles releases, just call itcodeclou---test-webhook-release.

We do not use 'Source Code Management' and we do not need to specify some 'Build Triggers' since it is all donemagically by convention over configuration.

Available Environment Variables from Webhook

Example Build Script Snippet

#!/bin/bashset -eecho"GWBT_COMMIT_BEFORE:$GWBT_COMMIT_BEFORE"echo"GWBT_COMMIT_AFTER:$GWBT_COMMIT_AFTER"echo"GWBT_REF:$GWBT_REF"echo"GWBT_TAG:$GWBT_TAG"echo"GWBT_BRANCH:$GWBT_BRANCH"echo"GWBT_REPO_CLONE_URL:$GWBT_REPO_CLONE_URL"echo"GWBT_REPO_HTML_URL:$GWBT_REPO_HTML_URL"echo"GWBT_REPO_FULL_NAME:$GWBT_REPO_FULL_NAME"echo"GWBT_REPO_NAME:$GWBT_REPO_NAME"## Cleanup before run#rm -rf$WORKSPACE/\.git||truerm -rf$WORKSPACE/*||truecd$WORKSPACE## Prevent manual Job starts#if [[-z"$GWBT_COMMIT_AFTER" ]]thenecho"I DON'T WANT JOBS STARTED MANUALLY! ONLY VIA GITHUB WEBHOOK!"exit 1fi## Do not build "delete branch push event"#if ["$GWBT_COMMIT_AFTER"=="0000000000000000000000000000000000000000" ]thenecho"DO NOT REACT ON BRANCH DELETE PUSHES"exit 0fi## Only Build Branches#if [-z"$GWBT_BRANCH" ]thenecho"THIS PUSH IS NOT INSIDE A BRANCH. I DON'T LIKE IT!"exit 1fi## Clone specific branch#git clone --single-branch \          --branch$GWBT_BRANCH \          https://github.com/${GWBT_REPO_FULL_NAME}.git \source## Switch to specific revision#cdsourcegit reset --hard$GWBT_COMMIT_AFTER## Trigger build script inside cloned repository#bash jenkins.sh

Example Build Script Snippet for Cloning Private Repositories

It is best to usePersonal Access Tokens.Put a Global Environment Variable namedGITHUB_AUTH_TOKEN in your Jenkins Configuration or specify at Job level.

Then you can clone a private repository like this:

## Clone specific branch#git clone --single-branch \          --branch$GWBT_BRANCH \          https://${GITHUB_AUTH_TOKEN}@github.com/${GWBT_REPO_FULL_NAME}.git \source

Usage with Pipeline Jobs

Since version 1.1.0Pipeline Job Types (NOT MultiBranch Pipeline) are supported.

Make sure you have at least the following Plugins installed.

‼️At best have thePipeline Bundle installed otherwise you might getjava.lang.ClassNotFoundException: org.jenkinsci.plugins.workflow.job.WorkflowJob Exceptions of some sort.

Pipeline: GroovyPipeline: JobPipeline: APIPipeline: Step APIPipeline: Stage StepPipeline: Basic StepsPipeline: Model API

A simpleJenkinsfile could look like this:

node {  stage('foo') {    sh'git clone --single-branch --branch ${env.GWBT_BRANCH}  https://github.com/${env.GWBT_REPO_FULL_NAME}.git source'    dir('source') {      sh'npm install'    }  }}

Totrigger build status of Pull Requests on GitHub.com you can do this via theGitHub Statuses REST API and your personal access token.

node {try {    stage('inform github') {      sh'curl -X POST -H\'Authorization: token'+ env.GITHUB_AUTH_TOKEN+'\''+' https://api.github.com/repos/${GWBT_REPO_FULL_NAME}/statuses/${GWBT_COMMIT_AFTER}'+' -d\'{ "state": "pending", "context": "Jenkins", "target_url": "'+ env.BUILD_URL+'", "description": "The build has started" }\''    }    stage('foo') {      sh'git clone --single-branch --branch ${env.GWBT_BRANCH}  https://github.com/${env.GWBT_REPO_FULL_NAME}.git source'      dir('source') {        sh'npm install'        sh'npm build'      }    }  }catch (Exception err) {    currentBuild.result='FAILURE'  }finally {if (currentBuild.result=='FAILURE') {      sh'curl -X POST -H\'Authorization: token'+ env.GITHUB_AUTH_TOKEN+'\''+' https://api.github.com/repos/${GWBT_REPO_FULL_NAME}/statuses/${GWBT_COMMIT_AFTER}'+' -d\'{ "state": "failure", "context": "Jenkins", "target_url": "'+ env.BUILD_URL+'", "description": "The build has failed" }\''    }else {      sh'curl -X POST -H\'Authorization: token'+ env.GITHUB_AUTH_TOKEN+'\''+' https://api.github.com/repos/${GWBT_REPO_FULL_NAME}/statuses/${GWBT_COMMIT_AFTER}'+' -d\'{ "state": "success", "context": "Jenkins", "target_url": "'+ env.BUILD_URL+'", "description": "The build was a success" }\''    }  }}

A pull request will now get status updates for each commit.

You can further enforce that a status check has to be successful in order to merge a PR. Go to via 'Settings' → 'Branches' → 'Add Branch protection rule'.

This is how it looks, when a Job gets triggered by a GitHub Webhook push.

Build Plugin

Have Jave Oracle Java 8 and Apache Maven 3 installed. And then build like this:

git clone https://github.com/codeclou/jenkins-github-webhook-build-trigger-plugin.gitcd jenkins-github-webhook-build-trigger-pluginmvn cleanmvn compilemvn hpi:hpi

Now you should have a file called./target/github-webhook-notifier-plugin.hpi whichyou can upload manually to Jenkins under 'Manage Plugins' → 'Advanced' → 'Upload Plugin'.

What's the story behind it?

I needed something that forcefully triggers my Jenkins Jobs by passing the actual git revision and branch or tag information.

The default behaviour of existing plugins is to receive the GitHub Webhook Payload, butonly using theafter commit id and "deciding if it needs to rebuild the job".

Example: You are on yourmaster Branch and you create a tag of off themaster branchand called1.0.0. When pushing1.0.0 tag, the jenkins job will not trigger an actual build.What happens? It will do some strangegit fetch requests and comes to the result, that the revisionwas already built with the previous push done bymaster branch. And partly he is right.Until further commits happen, themaster branch has the same revision as the1.0.0 tag.ButI want tag pushes to trigger a build anyway. And since I hate 'API-wrappers' of stuff,I decided to create a single purpose tool that just passes the information of the webhook payloadthrough to the job. And it is the jobs logic that can now decide what to do.

MIT ©Bernhard Grünewaldt