Set Up GitHub OAuth for Drone CI Authentication (2026)

GitHub OAuth is surprisingly not about letting GitHub decide who gets into your Drone CI instance; it’s about letting Drone CI ask GitHub if it should let someone in.

Let’s see it in action. Imagine a user, Alice, who hasn’t logged into Drone CI before.

1. Alice navigates to your-drone-domain.com/login.
2. She sees a "Login with GitHub" button.
3. Clicking it redirects her to GitHub’s authorization page, showing Drone CI requesting read:user and read:org scopes.
4. Alice approves.
5. GitHub redirects her back to Drone CI with an authorization code.
6. Drone CI exchanges this code with GitHub for an access token.
7. Using the token, Drone CI fetches Alice’s GitHub profile and organization memberships.
8. Drone CI then creates a session for Alice, granting her access based on the permissions derived from her GitHub identity.

The core problem this solves is secure, unified authentication. Instead of managing separate usernames and passwords for Drone CI, you leverage the trust already established with GitHub. This simplifies user management and significantly reduces the attack surface for credential theft.

Internally, Drone CI acts as a client application to GitHub’s OAuth 2.0 provider. The flow involves:

• Initiation: Drone CI redirects the user to GitHub’s authorization server with specific scope parameters.
• Authorization: The user logs into GitHub and grants permission.
• Callback: GitHub redirects the user back to Drone CI’s designated callback URL with an authorization code.
• Token Exchange: Drone CI exchanges this code with GitHub’s token endpoint for an access token.
• Resource Access: Drone CI uses the access token to query GitHub’s API for user and organization details.
• Session Creation: Based on the retrieved information, Drone CI creates a local user session.

The key levers you control are the GitHub Application settings and Drone CI’s configuration. In your GitHub repository, under Settings > Developer settings > OAuth Apps, you’ll create an application. You’ll need to set:

• Homepage URL: https://your-drone-domain.com (where your Drone instance is hosted).
• Callback URL: https://your-drone-domain.com/login/github/callback (the specific endpoint Drone CI listens on for the OAuth response).

In your Drone CI configuration (often via drone.yml or environment variables), you’ll provide:

• DRONE_GITHUB_CLIENT_ID: Your GitHub OAuth App’s Client ID.
• DRONE_GITHUB_CLIENT_SECRET: Your GitHub OAuth App’s Client Secret.
• DRONE_GITHUB_SCOPE: The permissions Drone CI requests, e.g., read:user,read:org.

When Drone CI receives the callback from GitHub, it uses the DRONE_GITHUB_CLIENT_ID and DRONE_GITHUB_CLIENT_SECRET to make a server-to-server request to GitHub’s /login/oauth/access_token endpoint. This request includes the code received from the callback. GitHub then validates the code and returns an access_token. Drone CI then uses this access_token to call GitHub’s /user and /user/orgs endpoints to get user details and group memberships, which it uses to authenticate the user locally.

A common point of confusion is the role of scopes. While you define scopes during GitHub App creation (e.g., read:user, read:org), Drone CI can also specify desired scopes in its configuration. If Drone CI requests scopes that were not granted by the user during the authorization step, it might fail to retrieve necessary information, leading to authentication issues. Always ensure the scopes listed in your Drone CI configuration are a subset of, or identical to, the scopes the user explicitly approved on GitHub.

The next hurdle is often configuring repository access, which is a separate step after initial authentication.