- How to store credentials of a GitHub “User X” in Jenkins?
- Which scopes does a GitHub “User X” needs for executing certain tasks in Jenkins?
- Which GitHub Organization permissions are needed for Multibranch Pipeline projects and Organization Folders?
- Cloudbees Jenkins Enterprise (CJE)
- GitHub plugin
- GitHub Pull Request Builder plugin
- CloudBees GitHub Pull Request Builder plugin
- Pipeline Multibranch Plugin
- GitHub Organization Folder Plugin
- Github Webhook
- GitHub OAuth Plugin
User Account: API Token and Scopes
At user level, GitHub uses Scopes for defining repository restrictions.
To generate an API token (“support-token”) for “User X”, log in “User X” account > Settings > Personal access tokens > Generate new token. Then, you should select the most proper scopes according to the task you would like to perform on Jenkins
Jenkins, in terms of GitHub Credentials, uses the API Token as pass the for different types of credentials:
- Username with Password:
Usernamecorresponds to the GitHub user ID of a “User X” and
Passwordto its API Token. This is the most extended case.
- Secret text type:
Secretcorresponds to the API Token of a “User X” of GitHub. This type is used for GitHub webhooks on Manage Jenkins -> Configure System -> GitHub Plugin Configuration
Jenkins’ scope requirements depends on the task/s you would like to perform:
admin:repo_hook- For managing hooks at GitHub Repositories level (including for multi branches)
admin:org_hook- For managing hooks at GitHub Organizations level (for folder organization)
repo- to see private repos. Please note that this is a parent scope, allowing full control of private repositories that includes:
repo:status- to manipulate commit statuses
repo:repo_deployment- to manipulate deployment statuses
repo:public_repo- to access to public repositories
user:email- recommended minimum for GitHub OAuth scopes
For GitHub OAuth Plugin, apart from the API token scopes, the GitHub application registration is also needed, generated Client ID and the Client Secret will be used to configure the Jenkins Security Realm.
Organization: Permissions for repositories
At organization level, GitHub uses Permission (normally associated to a Team) for defining repository restrictions.
In this context, there are three types of repository permissions available for people or teams collaborating on repositories:
Admin. Please, have a look at Github: Respository Permission Level for a Organization to understand better how each one works.
The workflow is as follows:
- Being a
Ownerof “Organization X”, Go to People > Invite member (“UserY”) to the “Organization X” and give it an appropriate role (
Member) in the organization.
- Once “UserY” accepts the invitation to the “Organization X”,
Ownershould go to People > Select “UserY” and assign it to a proper Team. That Team should have a set associated repositories with granted permissions.
To configure a GitHub WebHook manually as described on GitHub WebHook configuration
Owner role is needed.
Team List for a Organization
In this example (mock-carlosrodlop-org)
A team view
In this example (mock-carlosrodlop-org > myTeam)
Jenkins, in terms permission requirements, differs depending of the type of job:
Multibranch Pipeline and Github Organization Folder jobs
It is important to mention that for Multibranch Pipeline projects and Organization Folders for:
- Checkout credentials (used to clone the repository from GitHub), a user with
Readpermission in enough at repository level.
- Scan credentials (used to access the GitHub API), a user with
Writepermission is needed at repository level because all the interaction with the GitHub API is done by the user configured at this point. In particular,
Writepermission is needed for reading the list of collaborators in the repository.
If only Scan Credentials are set up, they will be used as Checkout Credentials too, meaning that git clones will be done by HTTPS.
Others types of jobs
For other type of jobs using GitHub as SCM, just setting up users with
Read permission at Organization repository level would be fine.
For GitHub Webhook with a “repoX” in a Organization:
- To send
Pull Requestevents from a fork repo towards “repoX”, a users needs to be granted at least with
- To send
Pushevents to “repoX”, a users needs to be granted at least with