Issue
- How to integrate GitHub (and/or GitHub Enterprise) with Jenkins.
- I would like to trigger Jenkins jobs from GitHub (and/or GitHub Enterprise) from a “GitHub API User” (GitHub User to interact with Jenkins).
Environment
- CloudBees Jenkins Enterprise - Managed controller (CJE-MM)
- CloudBees Jenkins Team (CJT)
- CloudBees Jenkins Platform - Client controller (CJP-CM)
- Jenkins LTS
- GitHub plugin
- GitHub
- GitHub Enterprise
- GitHub Webhook
Resolution
A. Plugin configuration
Go to Manage Jenkins > Configure System > GitHub section > Add a new GitHub Server Config
Add GitHub server/s managed by this Jenkins instance. So, if your Jenkins instance uses multiple repositories that are spread across different user accounts, you can list them all here as separate configs.
A.1 API URL
Two options:
- GitHub leave default
API URL. - GitHub Enterprise change the
API URLby its API endpoint (e.g. For “https://ghe.acme.com” and API version 3: “https://ghe.acme.com/api/v3/”).
A.2 Credentials
About Credentials
- You need Credentials for each of the GitHub/GitHub Enterprise Server added here.
- Jenkins needs a Personal API token to interact with the GitHub via webhooks.
This token can be either created manually or automatically (see next section). - Credentials from User:
Adminpermissions are required at the repository level butOwnerrole is required to create it at Organization level; For updating commit statuses / reading the list of collaborators,Writepermission is required.
You can find more information on the GitHub token permissions in GitHub Permissions and API token Scopes for Jenkins.
Setting up the Credentials
As explained in the previous section, the plugin needs a token to work. You can choose to let Jenkins create the token on your behalf, or create it manually.
-
Let Jenkins create the token: this option is only available if you are not using two-factor authentication.
You can make Jenkins generate the token by going to Advanced > Manage Additional GitHub Actions > Convert Login and Password to token. -
Generate the token yourself: first generate a token (make sure to read the previous section to understand what rights to grant). Then in the Credentials section (under the API URL) create a Credential of type
Secret Textand put the token you generated as a secret text.
You can then validate everything works as expected by clicking on Test Connection. If the credentials are correct a similar output to the following is expected:
Verify credentials
Credentials verified for user "GitHub-API-User", rate limit: 4994
Pay attention to the “GitHub API User” Rate limits.
In case of an error in the validation, make sure to take a Support Bundle right away with the controller’s Log Recorders activated.
This bundle will contain a stacktrace that will help the CloudBees Support troubleshoot your issue.
A.3 Manage hooks
Automatic Mode (Recommended)
Manage hooks: enabled
Jenkins create hooks in GitHub for you.
Manual Mode
Manage hooks: disabled
IMPORTANT: In this mode, you’ll be responsible for creating the webhook in GitHub under the following premises
- Payload URL, events and location (repository vs organization) must match with Validate GitHub WebHook section in GitHub Webhook: Non-Multibranch Jobs, GitHub Webhook: Pipeline Multibranch, GitHub Webhook: Organization Folder depending on the case.
- Content type should be set up as
application/json(application/x-www-form-urlencodedfor PR events in Freestyle Jobs)
B. Job Configuration
IMPORTANT: We recommend Multibranch Pipeline Jobs or GitHub Organization Folders.
Alternatively, you can use External HTTP Endpoints and define a eventTrigger per Jenkinsfile in each of the repo branches you wish to set the webhook (See this example). It offers more flexibility to filter the event information (payload) which triggers a build.
Depending of the type of jobs:
B.1 Non-Multibranch Jobs
See GitHub Webhook: Non-Multibranch Jobs
B.2 Pipeline Multibranch
See GitHub Webhook: Pipeline Multibranch
B.3 GitHub Organization Folder
See GitHub Webhook: Organization Folder
C. Troubleshooting
Tested products/plugins version
The latest update of this article was tested with:
Comments
9 comments
Where these instructions talk about "Manage hook URLs", they are referring to a single check box that you can get to by doing (from a Master or Client Master only)
Manage Jenkins > Configure System > GitHub > GitHub Servers and add one. Then you have to enter the GitHub URL, whether its at github.com or is an enterprise github instance with some local URL to your network.
Then you have to enter credentials to allow access to the GitHub instance (and the credentials have to have admin permission (or maybe somewhat less) to be able to create the hook.
But that only matters if you select the box "Manage hook URLs" because it won't try to use the credentials you entered on line n-1 if you you unselect the check box on line n. (The order is confusing if not utterly wrong.)
Note that when I went to this page from Google without logging in, I did not see any images and that left the text-only content very confusing. Particularly mentioning "Manage hook URLs" without any context whatsoever. Its a little better with images but still doesn't tell how to get to the page.
It is not intuitive that you go to add a build job and click to automatically build on a change but that doesn't work until you go to a whole different place in a different part of the web app to check a box and enter GitHub access info. But that is what this article describes.
"
Build when a change is pushed to GitHub" has beenoddly reworded to "GitHub hook trigger for GITScm polling" by https://github.com/jenkinsci/github-plugin/pull/162
In the mean time, the build behavior seems changed and not controllable from Jenkins anymore.Typo in section 3A.- : "None Multibranch" should be Non-Multibranch?
As of Jenkins 2.73.3:
"Manage hook URLs" checkbox is now "Manage hooks", and my experience agrees with @Carsique: it doesn't seem to matter what you set it to, you still have to go to GitHub and input your webhook URL. Names have changed in GitHub, too (I'm using GitHub Enterprise):
Since the automatic "Manage hooks" doesn't work, go to the GitHub repository you are working with, select Setting > Hooks & services.
Select "Add webhook"
In the "Payload URL" field, enter your httpx://<JENKINS_URL>/github-webhook/ url.
"Content type" - doesn't matter.
"Secret" - I left this blank.
"Just the push event." - trigger event
"Active" - checkbox filled.
Then select green "Add webhook" button.
FWIW, instead of adding a webhook, I tried adding the Jenkins (Git plugin) service on the GitHub Settings>Hooks & services page. It didn't work for me.
@Lee Meador, @Julien Carsique, @Gene Ratzlaff.
We have recently updated this article. Please let us know if you find it clearer or you have found any issues.
Regards,
"auto creating token does not work ..."
But no instructions on how to create the token by hand are given.
Hi Lee Meador
> But no instructions on how to create the token by hand are given.
In case it does not work for you, create your own API token as explained in https://github.com/blog/1509-personal-api-tokens
Regards
Hi, as I go through it I found topic named:
A.3 Manage hooks
Automatic Mode (Recommended)
In this whats exactly Automatic mode and we can set it to enabled, if we use multi-branch pipeline how we can proceed with hook triggering.
Hi,
is there a way to perform a different action from a Jenkinsfile according to the specific event received via webhook? Like differentiating the actions taken if the event is a push or a deployment, etc.
Thanks,
Christian
Hi,
@Deepti Singh
If we use multi-branch pipeline how we can proceed with hook triggering.
Multibranch Pipelines and Github Organization Folders create webhooks automatically as long as you configured the job and GitHub plugin correctly as explained in the guide.
@Christian Pinto
is there a way to perform a different action from a Jenkinsfile according to the specific event received via webhook? Like differentiating the actions taken if the event is a push or a deployment, etc.
CloudBees offers the External HTTP Endpoint feature which might help you with this request. Look at this example.
Best Regards,
Please sign in to leave a comment.