GitHub User Scopes and Organization Permission

Issue

  • 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?

Environment

  • Jenkins
  • 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

Resolution

API Token and Scopes

At user level, GitHub uses Scopes for defining repository restrictions.

Jenkins, in terms of Github Credentials, uses the API Token as pass the for different types of credentials:

  • Username with Password: Username corresponds to the GitHub user ID of a “User X” and Password to its API Token. This is the most extended case.
  • Secret text type: Secret corresponds 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

In order to generate an API token, log into GitHub “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:

  • 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
  • read:org and user:email - recommended minimum for GitHub OAuth scopes

github-token

GitHub OAuth

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

At organization level, GitHub uses Permission for defining repository restrictions.

In this context, there are three types of repository permissions available for people or teams collaborating on repositories: Read, Write and Admin. Please, have a look at the references to understand better how each one works.

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 Read permission in enough at repository level.
  • Scan credentials (used to access the GitHub API), a user with Write permission is needed at repository level because all the interaction with the GitHub API is done by the user configured at this point. In particular, Write permission 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.

References

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.