Jenkins GitHub WebHooks tutorial
I’ve seen a number of developers attempting to configure a GitHub to Jenkins webhook, only to be thwarted by the annoying 403 No valid crumb was included in the request error. Well I assure you, if you follow the steps outlined in this Jenkins GitHub webhook example, a 403 response code will not be your fate. Your future will be filled with nothing but HTTP status codes in the 200s.
To trigger a build with a GitHub webhook, you need a Jenkins job that uses a GitHub repository to invoke. For this example, I will create a freestyle Jenkins project with the following properties:
- Name: jenkins-github-webhook
- Git URL: https://github.com/learn-devops-fast/rock-paper-scissors.git
Along with these two setting you must also click the checkbox on the GitHub hook trigger for GITScm polling checkbox on the build job. This option is available so long as the Jenkins GitHub plugin is installed.
|Your intro to GitHub Actions training course|
Here’s how to get started with GitHub Actions:
Follow these tutorials and you’ll learn GitHub Actions fast.
Jenkins tokens and Webhook secrets
Finally, an API token in Jenkins must be generated to share as a secret key with the GitHub webhook.
Simply click on a Jenkins user, search for the configure option and click the Add new token button in the API token section for the user. Copy this long hexadecimal string, as this Jenkins API token will be the GitHub webhook secret.
With the Jenkins build job created and the API token copied, simple go to the Webhooks section of the Settings tab of the GitHub repository. Paste in the Jenkins API token as the secret, along with the IP address or domain name of your Jenkins server with /github-webhook/ appended as a URI.
With the GitHub webhook to Jenkins configured as a trigger, push commits to your GitHub repository at will. The GitHub server will then invoke our Jenkins instance and your continuous integration build jobs will run.
Steps for Jenkins GitHub Webhook integration
In review, the steps to configure a Jenkins GitHub webhook trigger is:
- Create a Jenkins build job that uses a GitHub URL
- Click the GitHub hook trigger for GITScm polling checkbox on the build job
- Create and copy a Jenkins API token for the Jenkins user who will run the build job
- Create a trigger in your GitHub repository’s settings page
- Set the GitHub payload URL to be your Jenkins’ IP address with /github-webhook/ appended to it
- Set the Jenkins API token as the GitHub webhook secret token
- Save the GitHub Webhook and then Jenkins builds will occur when a commit is pushed to the repo
Dreaded 403 no valid crumb in request errors
When Jenkins and GitHub actions are configured together, DevOps admins often run into the 403 no valid crumb in request error. This is triggered by trying to invoke the Jenkins build through the Trigger builds remotely option on the Jenkins job’s build page. This simply won’t work as a GitHub trigger for Jenkins. Instead, make sure the GitHub plugin for Jenkins is installed and the GitHub hook trigger for GitScm polling option is used instead.