About GitHub Authentication Plugin
The GitHub Authentication Plugin provides a means of using GitHub for authentication and authorization to secure Jenkins. GitHub Enterprise is also supported.
View GitHub Authentication on the plugin site for more information.
- About GitHub Authentication Plugin
- Other usage
- Open Tickets (bugs and feature requests)
- Release notes
Before configuring the plugin you must create a GitHub application registration.
- Visit https://github.com/settings/applications/new to create a GitHub application registration.
- The values for application name, homepage URL, or application description don't matter. They can be customized however desired.
However, the authorization callback URL takes a specific value. It must be
https://jenkins.example.com/securityRealm/finishLoginwhere jenkins.example.com is the location of the Jenkins server.
The important part of the callback URL is
- Finish by clicking Register application.
The Client ID and the Client Secret will be used to configure the Jenkins Security Realm. Keep the page open to the application registration so this information can be copied to your Jenkins configuration.
Security Realm in Global Security
The security realm in Jenkins controls authentication (i.e. you are who you say you are). The GitHub Authentication Plugin provides a security realm to authenticate Jenkins users via GitHub OAuth.
- In the Global Security configuration choose the Security Realm to be GitHub Authentication Plugin.
- The settings to configure are: GitHub Web URI, GitHub API URI, Client ID, Client Secret, and OAuth Scope(s).
If you're using GitHub Enterprise then the API URI is https://ghe.example.com/api/v3.
The GitHub Enterprise API URI ends with
The recommended minimum GitHub OAuth scopes are
The recommended scopes are designed for using both authentication and authorization functions in the plugin. If only authentication is being used then the scope can be further limited to
In the plugin configuration pages each field has a little next to it. Click on it for help about the setting.
Authorization in Global Security.
The authorization configuration in Jenkins controls what your users can do (i.e. read jobs, execute builds, administer permissions, etc.). The GitHub OAuth Plugin supports multiple ways of configuring authorization.
It is highly recommended that you configure the security realm and log in via GitHub OAuth before configuring authorization. This way Jenkins can look up and verify users and groups if configuring matrix-based authorization.
Github Committer Authorization Strategy
Control user authorization using the Github Committer Authorization Strategy. This is the simplest authorization strategy to get up and running. It handles authorization based on the git URL of a job and the type of access a user has to that project (i.e. Admin, Read/Write, Read-Only).
There is a way to authorize the use of the
/github-webhook callback url to receive post commit hooks from GitHub. This authorization strategy has a checkbox that can allow GitHub POST data to be received. You will still need to run the GitHub Plugin to have the message trigger the build.
Logged-in users can do anything
There are a few ways to configure the plugin so that everyone on your team has
- Choose Logged-in users can do anything authorization strategy.
- Choose one of the matrix-based authorization strategies. Set
anonymoususers to have
Overall/Readpermissions and perhaps the
Matrix-based Authorization strategy
Control user authorization using Matrix-based security or Project-based Matrix Authorization Strategy. Project-based Matrix Authorization Strategy allows one to configure authorization globally per project and, when using Project-based Matrix Authorization Strategy with the CloudBees folder plugin, per folder.
There are a few built-in authorizations to consider.
anonymous- is anyone who has not logged in. Recommended permissions are just
authenticated- is anyone who has logged in. You can configure permissions for anybody who has logged into Jenkins. Recommended permissions are
authenticatedusernames are case sensitive and must be lower case. This is a consideration when configuring authorizations via Groovy. Keep in mind that
anonymousshows up as Anonymous in the Jenkins UI.
You can configure authorization based on GitHub users, organizations, or teams.
username- give permissions to a specific GitHub username.
organization- give permissions to every user that belongs to a specific GitHub organization.
organization*team- give permissions to a specific GitHub team of a GitHub organization. Notice that organization and team are separated by an asterisk (
Calling Jenkins API using GitHub Personal Access Tokens
You can make Jenkins API calls by using a GitHub personal access token. One can still call the Jenkins API by using Jenkins tokens or use the Jenkins CLI with an SSH key for authentication. However, the GitHub OAuth plugin provides another way to call the Jenkins API by allowing the use of a GitHub Personal Access Token.
- Generate a GitHub Personal Access Token and give it only
- Use a username and GitHub personal access token to authenticate with the Jenkins API.
Here's an example using curl to start a build using parameters (username
samrocketman and password using the personal access token).
Automatically configure security realm via script console
Configuration management could be used to configure the security realm via the Jenkins Script Console. Here's a sample configuring plugin version 0.22.
Automatically configure authorization strategy via script console
Configuration management could be used to configure the authorization strategy via the Jenkins Script Console. Here's a sample configuring plugin version 0.22.
Open Tickets (bugs and feature requests)
|JENKINS-66302||Prepare GitHub Authentication for core Guava upgrade||Aug 07, 2021||Aug 29, 2021||Sam Gleske||Basil Crow||In Review||Unresolved|
|JENKINS-66292||Jenkins sessions with GitHub OAuth time out quickly, breaking usability||Aug 06, 2021||Aug 06, 2021||Sam Gleske||Jim Klimov||Open||Unresolved|
|JENKINS-66128||Github OAuth plugin should allow disabling rate limit checks||Jul 13, 2021||Jul 13, 2021||Sam Gleske||Brian Saville||Open||Unresolved|
|JENKINS-65937||Github Committer Authorization Strategy: user repository permissions||Jun 20, 2021||Jun 20, 2021||Sam Gleske||Samuel||Open||Unresolved|
|JENKINS-64162||Github Deprecating OAuth Authorization API||Nov 07, 2020||Nov 10, 2020||Sam Gleske||Shayne Clausson||Open||Unresolved|
|JENKINS-64090||Plugin authorization is not correctly handling case||Oct 30, 2020||Oct 30, 2020||Sam Gleske||Pierre Beitz||Open||Unresolved|
|JENKINS-63565||Receive HTTP 403 error authenticating with Github personal token||Aug 31, 2020||Oct 22, 2020||Sam Gleske||Lyndon Washington||Open||Unresolved|
|JENKINS-63421||Agent/Connect and other Agent permissions||Aug 18, 2020||Jul 01, 2021||Andreas Nygard||Andreas Nygard||In Progress||Unresolved|
|JENKINS-63051||Child teams should inherit rights granted to parent group||Jul 13, 2020||Oct 28, 2020||Sam Gleske||Clover BT||Open||Unresolved|
|JENKINS-61963||Authenticate github pull requester and trigger the build as him/her||Apr 18, 2020||Jun 04, 2020||Kanstantsin Shautsou||Michael Who||Open||Unresolved|
|JENKINS-60767||Make configurable call to authorize service||Jan 14, 2020||Jan 14, 2020||Sam Gleske||Seweryn Habdank-Wojewodzki||Open||Unresolved|
|JENKINS-60472||Jenkins authentication with GitHub not working||Dec 13, 2019||Dec 13, 2019||Unassigned||giby Alex||Open||Unresolved|
|JENKINS-60200||More control over cache||Nov 18, 2019||Nov 18, 2019||Sam Gleske||poh koh||Open||Unresolved|
|JENKINS-59372||Support cctray-xml plugin||Sep 13, 2019||Sep 13, 2019||Sam Gleske||Chris Griego||Open||Unresolved|
|JENKINS-58479||Failing to retrieve teams||Jul 12, 2019||Aug 26, 2019||Sam Gleske||Kote Mushegiani||Open||Unresolved|
|JENKINS-52528||Update github-api plugin from 1.77 to 1.93||Jul 12, 2018||Aug 10, 2019||Sam Gleske||Duncan Mak||Open||Unresolved|
|JENKINS-52382||Can't stop / cancel private repository builds||Jul 05, 2018||Aug 06, 2019||Sam Gleske||Clement Gautier||Open||Unresolved|
|JENKINS-52218||Creating a Multibranch pipeline job as an authenticated user via GitHub Committer Authorization Strategy results in error||Jun 27, 2018||Jun 27, 2018||Sam Gleske||steve bussetti||Open||Unresolved|
|JENKINS-50122||Incorrect permissions with non Multibranch based Pipeline jobs||Mar 12, 2018||May 01, 2019||Sam Gleske||Brice Figureau||Open||Unresolved|
|JENKINS-48601||Warn admin if he tries to configure GitHub authorization without authentication||Dec 18, 2017||Dec 19, 2017||Sam Gleske||Wadeck Follonier||Open||Unresolved|