> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibestrap.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub OAuth

> 在 GitHub 上注册一个 OAuth App，配两个环境变量，"用 GitHub 登录"按钮就来了。

做开发者向的产品，"用 GitHub 登录"的转化通常比邮箱注册高一截。Vibestrap 用
Better Auth 的社交 provider 接 GitHub——配好两个环境变量，按钮就会出现在
`/login` 和 `/register`。

## 前置条件

* 一个 GitHub 账号。
* 决定好生产域名。
* 5 分钟——三大平台里 GitHub 的 OAuth 流程最简单。

## 一步步配置

1. **打开 Developer settings**。[github.com/settings/developers](https://github.com/settings/developers)
   → OAuth Apps → **New OAuth App**。（如果挂在组织下，去
   `github.com/organizations/<org>/settings/applications`。）

2. **填表：**

   | 字段                         | 值                                                  |
   | -------------------------- | -------------------------------------------------- |
   | Application name           | 产品名（用户在授权页会看到）。                                    |
   | Homepage URL               | `https://your-domain.com`                          |
   | Authorization callback URL | `https://your-domain.com/api/auth/callback/github` |

   回调 URL 末尾**不要**带斜杠。本地开发再注册一个指向
   `http://localhost:3000/api/auth/callback/github` 的 OAuth App，dev 和 prod 用两个独立的 App。

3. **生成 client secret**。在 OAuth App 页点 **Generate a new client secret**。
   立刻复制——GitHub 只显示一次。

4. **写到 `.env.local`：**

   ```bash theme={null}
   GITHUB_CLIENT_ID=Iv1.abc123...
   GITHUB_CLIENT_SECRET=...
   ```

5. **打开按钮开关**。`src/config/site.ts`：

   ```ts theme={null}
   features: { enableGithubLogin: true, /* ... */ }
   ```

6. **重启 `pnpm dev`**。环境变量是启动时读的。

## Scope

Better Auth 默认请求 `read:user` 和 `user:email` ——够用来填 `user.name`、
`user.email`、`user.image`。除非你真要在用户身份下调 GitHub API，不要再要
`repo` 之类的 scope。要的越多，注册转化掉得越凶。

以后真要更宽的 scope（比如读用户的 repo），在 `src/lib/auth.ts` 里加 `scopes`：

```ts theme={null}
socialProviders.github = {
  clientId: env.GITHUB_CLIENT_ID,
  clientSecret: env.GITHUB_CLIENT_SECRET,
  scopes: ['read:user', 'user:email', 'repo'],
};
```

已存在的用户得重新授权，新 scope 才会生效。

## 验证是否生效

1. 访问 `/login`——"用 GitHub 登录"按钮应该出现。
2. 点一下，跳到 GitHub 授权页，点 Authorize，落回 `/dashboard`。
3. 看 `account` 表——应该有一行 `providerId = 'github'`，挂在你的 `user` 行下。
4. 先用邮箱注册，再用同邮箱的 GitHub 登一次——会合并成一个 `user`（账号合并对受信任 provider 是开的）。
5. 看 `user.image` 字段，应该是用户的 GitHub 头像 URL。

## 常见坑

* **回调 URL 带了末尾斜杠**。GitHub 是字符级精确匹配。`…/callback/github/`（带斜杠）
  和 `…/callback/github`（不带）不是一个东西。用不带斜杠的那个。
* **dev 和 prod 共用一个 OAuth App**。GitHub 免费 OAuth App 只允许一个回调 URL。
  建两个 App——`MyProduct (dev)` 和 `MyProduct (prod)`，各用各的 client ID。
  顺手把 dev 的 App 名字加 "(dev)" 后缀，授权页用户能一眼看出来这是开发环境。
* **没拿到邮箱权限**。有些用户把 GitHub 上所有邮箱都设成 private。Better Auth
  能跑——会回退到 `noreply` 邮箱。如果你必须发到他主信箱，第一次登录时弹个
  "请补全资料"的流程。
* **被组织限制的账号**。如果用户的 GitHub 组织强制 SSO，你的 OAuth App 要先被
  组织管理员批准，用户才能授权。
* **client secret 只显示一次**。GitHub 不会再显示第二次。丢了就重新生成——旧的立刻失效。
* **用户在 GitHub 上改了主邮箱**。Better Auth 不会自动同步——`user.email` 留的是
  注册那次的值。要追新可以加个 cron job 定期调 GitHub API 刷新。
* **GitHub Enterprise 实例**。默认走 `github.com`。如果接 GitHub Enterprise Server，
  得自定义 OAuth endpoint URL，开箱不支持。

## 官方文档

* 创建 OAuth App — [docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app)
* 授权 OAuth App — [docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps)
* OAuth App 的 Scope — [docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps)
* Better Auth GitHub provider — [better-auth.com/docs/authentication/github](https://www.better-auth.com/docs/authentication/github)