draft

docs/authentication/social-connections/github.mdx

@@ -3,34 +3,69 @@ title: Add GitHub as a social connection
 description: Learn how to set up social connection with GitHub.
 ---
 
-How to set up social connection with GitHub
+<TutorialHero
+  beforeYouStart={[
+    {
+      title: "A Clerk application is required.",
+      link: "/docs/quickstarts/setup-clerk",
+      icon: "clerk",
+    },
+    {
+      title: "A GitHub account is required.",
+      link: "https://github.com/signup",
+      icon: "user-circle",
+    },
+  ]}
+>
+  - Configure for your development instance
+  - Configure for your production instance
+</TutorialHero>
 
-## Overview
+Enabling OAuth with [**GitHub**](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app) allows your users to sign in and sign up for your Clerk application with their GitHub account.
 
-Adding social connection with GitHub to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Authorized redirect URI** in your instance settings.
+## Configure for your development instance
 
-To make the development flow as smooth as possible, Clerk uses  preconfigured shared OAuth credentials and redirect URIs for development instances - no other configuration is needed.
+For _development instances_, Clerk uses preconfigured shared OAuth credentials and redirect URIs—no other configuration is needed.
 
-For production instances, you will need to generate your own Client ID and Client secret using your GitHub account.
+1. Select **Add connection** and choose **For all users**.
+1. In the **Choose provider** dropdown, search for **GitHub**, then select **GitHub** from the list.
+1. Select **Add connection**.
 
-> [!NOTE]
-> The purpose of this guide is to help you create a GitHub account and a GitHub OAuth app - if you're looking for step-by-step instructions using Clerk to add social connection (OAuth) to your application, follow the [Social connection (OAuth) guide](/docs/authentication/social-connections/oauth).
+## Configure for your production instance
 
-## Before you start
+For _production instances_, you must provide custom credentials which involves generating your own **Client ID** and **Client Secret** using your GitHub account. This guide walks you through this process.
 
-- You need to create a Clerk Application in your [Clerk Dashboard](https://dashboard.clerk.com/). For more information, check out our [Set up your application guide](/docs/quickstarts/setup-clerk).
-- You need to have a GitHub account. To create one, [click here](https://github.com/signup).
+To make the setup process easier, we recommend keeping two browser tabs open: one for your [**Clerk Dashboard**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [**GitHub Developers**](https://GitHub.com/developers/applications) page.
 
-## Configuring GitHub social connection
+<Steps>
+  ### Enable GitHub as a social connection in Clerk
 
-First, you need to register a new OAuth GitHub app. Follow the official GitHub instructions on [how to create an OAuth app](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app).
+  1. In your Clerk Dashboard, go to **User & Authentication > [SSO Connections](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections)**.
+  1. Select **Add connection** and choose **For all users**.
+  1. In the **Choose provider** dropdown, search for **GitHub**, then select **GitHub** from the list.
+  1. The configuration options will appear below. Enable **Use custom credentials**. Keep the modal and page open throughout the guide.
 
-![Registering an OAuth GitHub app](/docs/images/authentication-providers/github/ff83ad81ca491cf17e5a755376fae9c88148ce7c-1395x799.png)
+  ### Set the Client ID and Client Secret in your Clerk Dashboard
 
-Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **GitHub**. Toggle on **Use custom credentials** and copy **Authorized redirect URI**. Go back to the GitHub panel, paste the value into the **Authorization callback URL** field and complete the registration.
+  1. On a separate page, go to [**GitHub's Developer Settings**](https://github.com/settings/apps) by selecting your profile photo in the top-right navigation, then choose **Settings**. In the sidebar, select **Developer settings**.
+  1. In the sidebar, select **OAuth Apps** then select [**New OAuth app**](https://github.com/settings/applications/new).
+  1. After being redirected to the **Register a new OAuth app** form, enter your **Application name** and **Homepage URL**. Keep the page open for the next step.
+  1. Navigate back to your **Clerk Dashboard**. In the **Add connection for all users** modal under the **Configure GitHub**, copy the **Authorized redirect URI**.
+  1. Navigate back to **GitHub** and paste the string in **Authorization callback URL**.
+  1. Select **Register application**.
+  1. After your application is created successfully, select your **Client ID**.
+  1. Navigate back to your **Clerk Dashboard**. Paste the string in **Client ID**.
+  1. Navigate back to **GitHub**. Select **Generate a new client secret**. Copy the **Client secret**.
+  1. Navigate back to your **Clerk Dashboard**. Paste the string in **Client secret**.
+  1. Select **Add connection**.
 
-Once registration is complete, you'll get redirected to project's admin panel. Click the **Generate a new client secret** button to get your new client secret. Then, copy the **Client ID** and **Client secret.** Go back to the Clerk Dashboard and paste them into the respective fields.
+  ### Test your OAuth
 
-![Obtaining the Client ID and Client secret](/docs/images/authentication-providers/github/3b1f58462fab3cc238c1a59994d1e2eb98f46b73-1489x964.png)
+  The simplest way to test your OAuth setup is by visiting your Clerk application's [Account Portal](/docs/customization/account-portal/overview), which is available out-of-the-box for all Clerk applications.
 
-Finally, select **Add connection** so that the settings are applied. Congratulations! Social connection with GitHub is now configured for your instance.
+  1. In the navigation sidebar of your **Clerk Dashboard**, select [**Account Portal**](https://dashboard.clerk.com/last-active?path=account-portal).
+  1. Next to the **Sign-in** URL, select **Visit**. The URL should resemble:
+     - **For development**: `https://your-domain.accounts.dev/sign-in`
+     - **For production**: `https://accounts.your-domain.com/sign-in`
+  1. On the sign-in page, you should see **GitHub** as an option. Use it to sign in with your GitHub account.
+</Steps>