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

# GitHub authentication

> How Amika authenticates to GitHub: the GitHub App, personal access tokens, and the runtime credential a sandbox uses for git.

Amika touches GitHub in two distinct ways, and it helps to keep them separate:

* **Repository discovery** — letting Amika see and select which repositories you
  can create sandboxes from. This is the GitHub App.
* **Runtime git credential** — the credential a sandbox uses to clone, push, and
  open pull requests. This is either a shared personal access token (PAT) or a
  per-user GitHub App token.

## Connect the GitHub App

The GitHub App controls which repositories Amika can see and select for
sandboxes. Connect it on
[app.amika.dev/settings/github](https://app.amika.dev/settings/github), in the
**GitHub App** panel, in two steps:

1. **Authorize GitHub** — click **Connect GitHub** and approve the OAuth
   authorization. This lets Amika act on your behalf to read the repositories you
   choose.
2. **Install the GitHub App** — click **Install GitHub App** and pick which
   repositories Amika can access. Installation happens on github.com; the
   settings page updates once it completes.

Connecting the app is per user — each teammate authorizes and installs it for
their own account. Once installed, the action becomes **Manage GitHub App**, and
you can revisit github.com to add or remove repositories at any time.

## Set the git author

On the same page, **Git Author** sets the name and email used for git commits
made inside sandboxes. Amika pre-fills this from your profile and saves it
automatically, so most users never need to change it.

## Runtime git credential: PAT vs. GitHub App token

When a sandbox runs git commands, it needs a credential. Amika supports two
modes.

### Personal access token (PAT)

A single organization-wide token, shared across your org. Every teammate can use,
replace, or delete it. This is the default runtime credential.

Set it up in the **GitHub Access Token** section of
[settings/github](https://app.amika.dev/settings/github):

1. Click **Create GitHub PAT Token** to open GitHub's fine-grained token page.
2. Grant the permissions below.
3. Paste the token (it starts with `github_pat_`) into **Organization Access
   Token** and click **Save**.

Required permission:

* **Contents** → Read and Write — clone, pull, push branches, and create commits.

Recommended permissions:

* **Pull requests** → Read and Write — create and update PRs from the sandbox.
* **Issues** → Read and Write — read and create issues from the sandbox.
* **Actions** → Read — monitor GitHub Actions so agents can auto-fix CI.

The token is stored once and reused by every sandbox in the org until it is
replaced or deleted.

### GitHub App token

Instead of a shared static token, a sandbox can authenticate as the creating
user's GitHub App connection. In this mode:

* There is no shared secret to manage — it uses the per-user GitHub App
  connection you set up above.
* Tokens are minted at runtime through a git credential helper, so no long-lived
  credential is ever written to disk inside the sandbox.
* The creating user must have the GitHub App connected. Without it, sandbox
  creation fails with a message asking you to connect GitHub in settings first.

## Which mode should you use?

|                | PAT                                 | GitHub App token                                     |
| -------------- | ----------------------------------- | ---------------------------------------------------- |
| Scope          | One shared token for the whole org  | Per user, tied to each user's GitHub connection      |
| Setup          | Create and paste a fine-grained PAT | Connect and install the GitHub App                   |
| Secret on disk | Static token, stored and reused     | Short-lived tokens minted at runtime; none persisted |
| Attribution    | Shared identity                     | The creating user's identity                         |

Use a **PAT** for the simplest shared setup, or when you want one credential to
administer centrally. Prefer the **GitHub App token** when you want per-user
attribution and no shared long-lived secret. Which mode a given sandbox uses is
determined by your platform configuration; both require the corresponding
credential to be present.

<Note>
  Regardless of runtime mode, the GitHub App still governs which repositories are
  selectable in the UI. Connect and install it before creating sandboxes.
</Note>

## Next steps

<CardGroup>
  <Card title="Create a sandbox" href="/guides/create-a-sandbox" icon="cube" />

  <Card title="Inject credentials" href="/guides/inject-credentials" icon="key" />

  <Card title="Authentication reference" href="/reference/auth" icon="lock" />
</CardGroup>