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

# GitHub

> Wire GitHub OAuth 2.0 into KavachOS with the `oauth()` plugin. Covers app registration, callback URL, client secret setup, and optional scope expansion.

## Get credentials

<Steps>
  <Step>
    ### Register an OAuth App

    Go to [github.com/settings/applications/new](https://github.com/settings/applications/new) (personal account) or **Organization Settings > Developer Settings > OAuth Apps** for an org app.

    * **Application name**: your app name
    * **Homepage URL**: `https://example.com`
    * **Authorization callback URL**: `https://auth.example.com/auth/oauth/github/callback`
  </Step>

  <Step>
    ### Copy credentials

    After creating the app, copy the **Client ID**. Click **Generate a new client secret** and copy the secret immediately. GitHub only shows it once.
  </Step>
</Steps>

<Info>
  GitHub also supports GitHub Apps, which have more granular permissions and work across organizations. OAuth Apps are simpler for sign-in use cases.
</Info>

## Configuration

<Tabs>
  <Tab title="Basic">
    ```typescript title="lib/kavach.ts" theme={"system"}
    import { createKavach } from 'kavachos';
    import { oauth } from 'kavachos/auth';

    const kavach = await createKavach({
      database: { provider: 'postgres', url: process.env.DATABASE_URL! },
      secret: process.env.KAVACH_SECRET!,
      baseUrl: 'https://auth.example.com',
      plugins: [
        oauth({
          providers: [
            {
              id: 'github', // [!code highlight]
              clientId: process.env.GITHUB_CLIENT_ID!, // [!code highlight]
              clientSecret: process.env.GITHUB_CLIENT_SECRET!, // [!code highlight]
            },
          ],
        }),
      ],
    });
    ```
  </Tab>

  <Tab title="With extra scopes">
    ```typescript title="lib/kavach.ts" theme={"system"}
    oauth({
      providers: [
        {
          id: 'github',
          clientId: process.env.GITHUB_CLIENT_ID!,
          clientSecret: process.env.GITHUB_CLIENT_SECRET!,
          scopes: ['user:email', 'read:org'], // [!code highlight]
        },
      ],
    })
    ```
  </Tab>
</Tabs>

```bash theme={"system"}
GITHUB_CLIENT_ID=Ov23li...
GITHUB_CLIENT_SECRET=...
```

## Scopes

Default scope: `user:email`

| Scope        | What it unlocks                 |
| ------------ | ------------------------------- |
| `user:email` | Read the user's email addresses |
| `read:user`  | Read the user's profile data    |
| `read:org`   | Read organization membership    |
| `repo`       | Access private repositories     |

## User data returned

| Field   | Source                 | Notes                            |
| ------- | ---------------------- | -------------------------------- |
| `id`    | `id` field             | Stable numeric GitHub user ID    |
| `email` | Primary verified email | Fetched separately if not public |
| `name`  | `name` field           | Display name, may be null        |
| `image` | `avatar_url`           | GitHub avatar URL                |

<Warning>
  GitHub users can set their email to private. KavachOS fetches the primary verified email from the `/user/emails` endpoint using the `user:email` scope, so you still get it even if the profile email is hidden.
</Warning>