# Set up Sign in with GitHub Put a GitHub button on your sign-in page. Register an OAuth App on GitHub, paste its client ID and secret into BuildBase, and set its callback URL. Sign in with GitHub puts a **GitHub** button on your hosted sign-in page. The person presses it, approves your app on GitHub's own page, and comes back signed in. It suits apps for software developers, who nearly all have a GitHub account. You register an **OAuth App** in your GitHub developer settings (OAuth is the standard way one site lets another confirm who someone is), copy its client ID and a client secret into BuildBase, and give GitHub one address from BuildBase as the app's callback URL. > **Note:** - A GitHub account. An OAuth App can belong to you or to a GitHub organization you manage, such as `acme`. - An app in the BuildBase console, on the **Settings** tab of **Authentication**. Here it is **Acme Analytics**. - Room on your plan. GitHub counts toward your plan's limit of social sign-in providers. ## What goes where | Copy this | From | Paste it into | | ------------- | ---------------------------------------- | -------------------------------------- | | Client ID | GitHub, your OAuth App's page | BuildBase, **Client ID** | | Client secret | GitHub, **Generate a new client secret** | BuildBase, **Client secret** | | Redirect URL | BuildBase, after you press **Create** | GitHub, **Authorization callback URL** | A GitHub client ID looks like `Ov23liAcmeExample0001`. It is not secret. The client secret is: GitHub shows it once, so copy it straight away. ## 1. Register the OAuth App on GitHub These are the steps the console shows under **How to get your GitHub keys**. 1. Open [Developer settings on GitHub](https://github.com/settings/developers), then **OAuth Apps**. For an organization's app, open the organization's **Settings**, then **Developer settings**. 2. Choose **New OAuth App** (**Register a new application** if it is your first). Give it your app's name, such as `Acme Analytics`, and your website's address as the **Homepage URL**, such as `https://app.acme.example`. 3. GitHub asks for an **Authorization callback URL** now. Type your website's address for the moment. You replace it at the end of the next part. 4. Click **Register application**. Copy the **Client ID**, then choose **Generate a new client secret** and copy that at once: GitHub shows it only once. Choose an **OAuth App**, not a GitHub App, and use one OAuth App for each BuildBase GitHub method, such as one for production and one for a staging organization. Each one gets exactly one callback URL, the one the console shows you in the next part: see [one callback URL](#one-callback-url) for why. ## 2. Add GitHub in the BuildBase console 1. In the console, open **User management**, then **Authentication** under **Access**, and the **Methods** tab. 2. Press **Add auth method** and choose **GitHub**. The dialog opens **How to get your GitHub keys**, the steps above. ![The Add new method dialog with GitHub chosen, and the open guide How to get your GitHub keys with its six steps](/images/sign-in-setup/github/console-choose.webp) 3. Fill in the form: - **Title**: your own name for the method, shown in the console only. The button your users see always says GitHub. - **Client ID** and **Client secret**: paste them from GitHub. - **Scopes**: keep `user:email` and `read:user`. `user:email` lets BuildBase read the person's email address even when they keep it private on GitHub, and a new account is made with it. ![The GitHub form filled in: Title GitHub, Client ID Ov23liAcmeExample0001, Client secret hidden as dots, and the default scopes user:email and read:user](/images/sign-in-setup/github/console-form.webp) 4. Press **Create**. The dialog says **One step left** and shows the **Redirect URL**. Press **Copy**. ![After Create: One step left, and the Redirect URL box with the address to paste into Authorization callback URL on GitHub](/images/sign-in-setup/github/console-redirect-url.webp) 5. Press **Done**. 6. On GitHub, open the OAuth App, paste the URL into **Authorization callback URL** in place of your website's address, and click **Update application**. Leave it as the only callback URL the OAuth App has. ### One callback URL Register exactly one **Authorization callback URL** on the OAuth App: the redirect URL the console shows, and nothing else. BuildBase sends GitHub no callback address of its own, so GitHub returns every sign-in to the one the OAuth App has registered. With only that one, GitHub can return people to that exact address and to no other, which is what the OAuth security best practice (RFC 9700) asks for. With several, GitHub uses the first one, so a sign-in for any other BuildBase method lands on the wrong callback and is refused. The redirect URL has this shape: ```text https://api.console.buildbase.app/api/v1/auth/social/github///callback ``` It starts with your BuildBase server, https://api.console.buildbase.app on BuildBase's cloud. Copy it rather than typing it. It never changes while the method exists; deleting the method and adding GitHub again makes a new one. **The secret stays hidden.** Open the method again later with the edit button on its row and the **Client secret** box is empty. The line under it shows the saved secret's first and last five characters. Leave the box empty to keep it, or paste a new secret to replace it. ![Editing the GitHub method: the Client ID as saved, and under Client secret the note Saved, followed by the first and last five characters of the secret, with Leave this empty to keep it](/images/sign-in-setup/github/console-edit-saved.webp) ## 3. Attach it to your app 1. Open the **Settings** tab and press **Edit** on **Acme Analytics**. 2. Under **Methods**, tick **GitHub** and press **Update**. The console says **Client saved**. ![The Edit auth setting sheet for Acme Analytics, at Methods: GitHub ticked beside Email and password](/images/sign-in-setup/github/console-attach.webp) ## 4. Check the preview Open the **Sign-in page** tab. Its **Preview** draws a sample card, and the sample's social buttons are always GitHub and Google, so it shows where your buttons sit and how they look rather than which ones your app has. Press **Open the live page for Acme Analytics** above it to open your real page in a new tab. ![The Preview on the Sign-in page tab, with the button Open the live page for Acme Analytics, and a sample sign-in card whose social buttons are always GitHub and Google](/images/sign-in-setup/google/console-preview.webp) ## 5. What people see The hosted sign-in and register pages now have a **GitHub** button under the email and password form. ![The hosted sign-in page Sign in to Acme, with the email and password form and, under or, a GitHub button](/images/sign-in-setup/github/hosted-button.webp) Pressing it opens GitHub's page, which asks the person to authorize your OAuth App the first time. GitHub then sends them back, and the sign-in page carries on as after any sign-in: a second step if your [two-step policy](/sign-in-setup/two-step) asks social sign-ins for one, **Trust this device?**, and the passkey offer if your app offers passkeys. ### The first sign-in - **The email address** is the one public on the person's GitHub profile, or else their primary verified address. GitHub lets only a verified address be public, so BuildBase treats either as verified, and a new account gets no verification code. A GitHub account with no verified address cannot sign in: the page asks the person to verify an email address on GitHub and try again. - **The name** is their GitHub name, or their username when they have not set one. - **Finding the account**: by their GitHub user ID first, then by that verified email address, which connects GitHub to an account made another way, then as a new account if sign-up is open to them and your plan has room. See [who can sign up](/sign-in-setup/sign-up-access). - **The same ID everywhere.** GitHub gives a person the same user ID in every OAuth App, so GitHub sign-ins you [import](/sign-in-setup/importing-users) from another system match, whichever OAuth App you use here. Someone who signed up with GitHub has no password. They can make one later with **Forgot password?** on a client that offers email and password. ## In your app Nothing changes in your code. People manage connected accounts, GitHub included, on the SDK's Security screen: see [Account security screens](/sign-in-setup/account-security-screens). ```tsx import { useSaaSAuth } from '@buildbase/sdk/react'; export function SecurityButton() { const { openWorkspaceSettings } = useSaaSAuth(); return ( ); } ``` ## Check it works - [ ] **GitHub** is in the **Login methods** list. - [ ] The OAuth App's only **Authorization callback URL** is the redirect URL from the console, not your website. - [ ] **GitHub** is ticked on your app, and **Open the live page** shows the button. - [ ] Signing in with a GitHub account creates a user, and signing in again reaches the same one. ## Things to watch out for - **One callback URL, and one OAuth App for each method.** BuildBase does not tell GitHub which callback URL to use. Since August 2026 an OAuth App can hold up to 10 callback URLs, and GitHub then sends people to the first one. Keep exactly one, the console's redirect URL, and give each BuildBase GitHub method its own OAuth App. See [one callback URL](#one-callback-url). - **The GitHub account needs a verified email address.** BuildBase uses the public address on the profile, or else the primary verified one. An account with neither is refused with "Your account with that provider has no verified email address. Verify an email address there, then try again." - **Finish at GitHub within 10 minutes.** A sign-in left open on GitHub's page for more than 10 minutes cannot finish: BuildBase sends the browser to your sign-in page, with a note that the sign-in expired. Start again from your app's **Sign in** button. ## If something goes wrong | What you see | Why | What to do | | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | After GitHub, the person lands on your website instead of being signed in | The **Authorization callback URL** is still your website's address | Paste the redirect URL from the console into it, and click **Update application**. | | After GitHub, a plain "Unauthorized" page from your BuildBase server | GitHub sent the person to another BuildBase method's callback: the OAuth App has several callback URLs, or two methods share it | Keep exactly one callback URL, this method's, and give each method its own OAuth App. | | Your sign-in page, with a note that the sign-in expired | The person took more than 10 minutes on GitHub's page, or came back to it after finishing | Start again from your app's **Sign in** button. | | Sign-in with that provider did not finish. Please try again. | The person pressed **Cancel** on GitHub, or GitHub answered with an error (`provider_error`) | Try again. | | Sign-in with that provider failed. Please try again. | BuildBase could not finish with GitHub, most often a wrong client secret (`provider_failed`) | Generate a new client secret and paste it in. | | Your account with that provider has no verified email address. Verify an email address there, then try again. | The GitHub account has no verified address (`no_verified_email`) | Ask the person to verify an address on GitHub. | | This email is already registered. Sign in the way you did before, then connect this provider from your account's security settings. | An account has this address, and GitHub did not vouch for it (`email_unverified`) | The person signs in the way they did before, then connects GitHub from the Security screen. | | This provider did not share an email address, so an account cannot be created. Allow access to your email address and try again. | The scopes no longer reach the address (`email_missing`) | Clear the **Scopes** box to go back to the defaults. | | Sign-up is invite-only here, and there is no account for that address yet. Ask the team for an invitation, or sign in with an account you already have. | Public sign-up is off (`signup_disabled`) | Invite the person, or open sign-up. | | Sign-up isn't available for this address. | The address is blocked or not on your allowlist (`signup_restricted`) | Change the lists in **Who may sign up**. | | Join the waitlist, and you can sign up once you're approved. | Sign-up is by waitlist (`waitlist_required`) | Approve them on the waitlist. | | This app is not taking new sign-ups right now. | Your plan's end-user limit is reached (`signup_unavailable`) | Upgrade, or remove users you no longer need. | | Your account has been blocked. Please contact support for assistance. | The account is blocked (`blocked`) | Unblock the user in the console if that was a mistake. | | In the console: Your plan includes 2 social sign-in providers. Upgrade for more, or remove one. | Your plan's social provider limit is reached; the number is your plan's | Upgrade, or delete a provider you no longer use. | When the person cancels on GitHub, they come back to the sign-in page with the message above the form: ![The sign-in page back from GitHub with the message Sign-in with that provider did not finish. Please try again. above the form, which is still there to try again](/images/sign-in-setup/github/hosted-refused.webp) ## Next steps - [Social providers](/authentication/social-providers#github) - the reference for every provider. - [Importing users](/sign-in-setup/importing-users) - bring people over with their GitHub sign-ins. - [Account security screens](/sign-in-setup/account-security-screens) - connected accounts inside your app. - [Set up sign-in, step by step](/sign-in-setup/overview) - every sign-in guide, and the order to set them up in.