GitHub Permissions and personal access token Scopes for Jenkins

Article ID:234710368
2 minute readKnowledge base

Issue

  • How to store credentials of a GitHub "User X" in Jenkins?

  • Which scopes does a personal access token need for executing certain tasks in Jenkins?

Resolution

Introduction to GitHub Permissions

Within in an Organization, each Repository defines its restrictions by Permission associated to Team/s and Collaborator/s.

  • There are 2 Roles within a GitHub Organization: Owner or Member.

  • A GitHub user becomes a Member by "joining" an Organization (by default). Note: An invitation from an Owner is needed beforehand.

  • Members within an GitHub Organization can be distributed in Teams. A member can join one or more teams.

  • Collaborators (members or external user from the organization) and teams can be defined for each repository. For each of them should be assigned a Permission Level

GitHub Credentials for Jenkins

It depends on the specific configuration:

Checkout Credentials

  • On GitHub, a user with Read permission is enough.

  • On Jenkins, it supports Username with Password credentials. Username is the GitHub user ID and Password is the Password or your personal access token.

Scan Credentials: For GitHub and Jenkins API interactions.

  • On GitHub, it depends on the interaction. For webhooks Admin permissions are required at the repository level but Owner role is required to create it at Organization level; For updating commit statuses / reading the list of collaborators, Write permission is required.

  • On Jenkins, it can be stored as: (1) Username with Password (Password: personal access token) at Job Configuration (Multibranch Pipelines and GitHub Organization Folder) or (2) Secret text type (Secret: personal access token) at GitHub plugin configuration.

Pull Request and Push Permissions

  • To be able to create a Pull Request in "repoX", a users needs to be granted at least with Read permissions. (actually the Read permission is required to be able to create a fork)

  • To be able to commit changes to "repoX", a users needs to be granted at least with Write permissions.

GitHub personal access token scopes for Jenkins

Jenkins' scope requirements depends on the task/s you wish like to perform:

  • admin:repo_hook - For managing hooks at GitHub Repositories level including for Multibranch Pipeline

  • admin:org_hook - For managing hooks at GitHub Organizations level for GitHub Organization Folders

  • 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 Authentication plugin scopes.

You can create the personal access token now by login with the GitHub user and click here
personal access token
This article is part of our Knowledge Base and is provided for guidance-based purposes only. The solutions or workarounds described here are not officially supported by CloudBees and may not be applicable in all environments. Use at your own discretion, and test changes in a safe environment before applying them to production systems.