GitHub - User Scopes and Organization Permissions Overview

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
  • GitHub OAuth Plugin

Resolution

User Account: API Token and Scopes

On GitHub

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

Github Web hook auto

On Jenkins

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

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

GitHub OAuth

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

On GitHub

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: Read, Write and 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:

  1. Being a Owner of “Organization X”, Go to People > Invite member (“UserY”) to the “Organization X” and give it an appropriate role ( Owner or Member) in the organization.
  2. Once “UserY” accepts the invitation to the “Organization X”, Owner should 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)

Github Team view 1

A team view

In this example (mock-carlosrodlop-org > myTeam)

Github Team view 2

On Jenkins

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.

For GitHub Webhook with a “repoX” in a Organization:

  • To send Pull Request events from a fork repo towards “repoX”, a users needs to be granted at least with Read permissions.
  • To send Push events to “repoX”, a users needs to be granted at least with Write permissions.

References

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.