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).
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
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 on the type of jobs: