# GitHub (/docs/authentication/github)

GitHub 提供者的设置和使用。



<Steps>
  <Step>
    ### 获取 GitHub 凭证 [#获取-github-凭证]

    要使用 GitHub 登录，你需要一个客户端 ID 和客户端密钥。你可以从 [GitHub 开发者门户](https://github.com/settings/developers) 获取它们。

    确保将重定向 URL 设置为 `http://localhost:3000/api/auth/callback/github`，用于本地开发。生产环境中，应将其设置为应用程序的 URL。如果更改了认证路由的基本路径，需要相应地更新重定向 URL。

    重要：你必须在 GitHub 应用中包含 `user:email` 范围。详见下文。
  </Step>

  <Step>
    ### 配置提供者 [#配置提供者]

    要配置提供者，你需要导入该提供者并将其传递给认证实例的 `socialProviders` 选项。

    ```ts title="auth.ts"
    import { betterAuth } from "better-auth"

    export const auth = betterAuth({
        socialProviders: {
            github: { // [!code highlight]
                clientId: process.env.GITHUB_CLIENT_ID as string, // [!code highlight]
                clientSecret: process.env.GITHUB_CLIENT_SECRET as string, // [!code highlight]
            }, // [!code highlight]
        },
    })
    ```
  </Step>

  <Step>
    ### 使用 GitHub 登录 [#使用-github-登录]

    要使用 GitHub 登录，可以使用客户端提供的 `signIn.social` 函数。`signIn` 函数接收一个包含以下属性的对象：

    * `provider`：要使用的提供者。应设置为 `github`。

    ```ts title="auth-client.ts"  
    import { createAuthClient } from "better-auth/client"
    const authClient =  createAuthClient()

    const signIn = async () => {
        const data = await authClient.signIn.social({
            provider: "github"
        })
    }
    ```
  </Step>
</Steps>

## 使用说明 [#使用说明]

### 设置你的 GitHub 应用 [#设置你的-github-应用]

GitHub 有两种应用类型：GitHub 应用和 OAuth 应用。

对于 OAuth 应用，无需执行特殊操作（只需按照上述步骤操作）。对于 GitHub 应用，你需要额外完成一项设置，即开启读取用户邮箱的权限：

1. 创建应用后，进入 *权限和事件* > *账户权限* > *电子邮件地址* 并选择“只读”（Read-Only）

2. 保存更改。

这样就可以了！现在你可以复制应用的客户端 ID 和客户端密钥！

<Callout>
  如果你遇到 `email_not_found` 错误，通常是因为：（a）你创建了一个 GitHub App，但没有授予“Email addresses: Read-only”权限；或者（b）用户将其主邮箱设置为私密，在这种情况下 `GET /user` 会返回 `email: null`。有关推荐的 `mapProfileToUser` 回退方案，请参阅[处理无邮箱提供者](/docs/concepts/oauth#处理不提供邮箱的提供商)；用户的私密地址也可通过 [`/user/emails`](https://docs.github.com/en/rest/users/emails) 获取。
</Callout>

### 为什么我没有刷新令牌？ [#为什么我没有刷新令牌]

GitHub 不为 OAuth 应用发放刷新令牌。对于常规 OAuth 应用，GitHub 发放的访问令牌除非用户撤销、应用撤销，或者一年内未使用，否则将一直有效。

不需要刷新令牌，是因为访问令牌不像 Google 或 Discord 那样在短时间内过期。