GitHub Permissions and API token Scopes for Jenkins


  • How to store credentials of a GitHub “User X” in Jenkins?
  • Which scopes does an API token need for executing certain tasks in Jenkins?



Context: Jenkins with GitHub

Introduction to GitHub Permissions

Within in a 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 before hand.
  • 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

As a summary: Repository permission levels for an organization.

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 a personal API Token (recommended).

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 API Token) at Job Configuration (Multibranch Pipelines and GitHub Organization Folder) or (2) Secret text type (Secret: personal API 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 API 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 OAuth Plugin scopes.

Note: You can create the API-Token now by login with the GitHub user and click here

API token

Have more questions?


  • 0
    John Hill

    This was very helpful. I used this guide to help clarify that:

    Username is the GitHub user ID and Password is the Password orpersonal API Token (recommended).

    The contextual in-line help (and gitScm pipeline step error handling) don't mention that a pure 'Secret Text' API Token cannot be used without the username.

    Effectively, Github use in Jenkins requires a Github service account to be managed by operations/IT. 

    Edited by John Hill
  • 0
    Carlos Rodriguez Lopez

    Thanks @john hill

Please sign in to leave a comment.