GitHub
Get your GitHub credentials
To use GitHub sign in, you need a client ID and client secret. You can get them from the GitHub Developer Portal.
Make sure to set the redirect URL to http://localhost:3000/api/auth/callback/github for local development. For production, you should set it to the URL of your application. If you change the base path of the auth routes, you should update the redirect URL accordingly.
Important: You MUST include the user:email scope in your GitHub app. See details below.
Configure the provider
To configure the provider, you need to import the provider and pass it to the social_providers option of the auth instance.
require "better_auth"
auth = BetterAuth.auth(
secret: ENV.fetch("BETTER_AUTH_SECRET"),
base_url: ENV.fetch("BETTER_AUTH_URL", "http://localhost:3000"),
social_providers: {
github: BetterAuth::SocialProviders.github(
client_id: ENV.fetch("GITHUB_CLIENT_ID"),
client_secret: ENV.fetch("GITHUB_CLIENT_SECRET")
)
}
)Sign In with GitHub
To sign in with GitHub, call auth.api.sign_in_social on your Ruby auth instance. The endpoint body takes the following properties:
provider: The provider to use. It should be set togithub.
response = auth.api.sign_in_social(
body: {
provider: "github",
callback_url: "/dashboard",
error_callback_url: "/login",
disable_redirect: true
}
)
redirect_url = response.fetch(:url)Usage
Setting up your Github app
Github has two types of apps: Github apps and OAuth apps.
For OAuth apps, you don't have to do anything special (just follow the steps above). For Github apps, you DO have to add one more thing, which is enable it to read the user's email:
-
After creating your app, go to Permissions and Events > Account Permissions > Email Addresses and select "Read-Only"
-
Save changes.
That's all! Now you can copy the Client ID and Client Secret of your app!
If you get an email_not_found error, it is most often because either (a) you created a GitHub App and did not grant the "Email addresses: Read-only" permission, or (b) the user has set their primary email to private, in which case GET /user returns email: null. See Handling Providers Without Email for the recommended map_profile_to_user fallback; the user's private addresses are also available via /user/emails.
Why don't I have a refresh token?
Github doesn't issue refresh tokens for OAuth apps. For regular OAuth apps, GitHub issues access tokens that remain valid indefinitely unless the user revokes them, the app revokes them, or they go unused for a year. There's no need for a refresh token because the access token doesn't expire on a short interval like Google or Discord.