> ## 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 rig 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 rigs from. This is the GitHub App.
* **Runtime git credential**: the credential a rig uses to clone, push, and
  open pull requests. This is either a per-user GitHub App token (the default)
  or a shared personal access token (PAT).

## Connect the GitHub App

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

1. Click **Connect GitHub**.
2. Approve the authorization on github.com, then pick which repositories
   Amika can access. The settings page updates once you return.

Connecting the app is per user: each teammate connects it for their own
account. Once connected, the panel shows **Manage repositories**, which opens
github.com so you can add or remove repositories at any time, and **Disconnect
account**, which removes your GitHub authorization. Disconnecting leaves the
GitHub App installed until you remove it on GitHub.

## Set the git author

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

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

When a rig runs git commands, it needs a credential. Amika supports two
modes. Pick the default for your organization in the **GitHub Access** panel
of [settings/github](https://app.amika.dev/settings/github), under **Default
auth mode**, then click **Save**. The setting applies to every new rig in
your organization.

### GitHub App token

**App Token (recommended)** is the default. Instead of a shared static token,
each rig authenticates 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 rig.
* The creating user must have the GitHub App connected. Without it, rig
  creation fails with a message asking you to connect GitHub in settings first.

### Personal access token (PAT)

A single organization-wide token, shared across your org. Every teammate can use,
replace, or delete it. The **PAT** option under **Default auth mode** stays
disabled until a token is saved.

Set it up in the **GitHub PAT (optional)** section of the same panel:

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 rig.
* **Issues** → Read and Write: read and create issues from the rig.
* **Actions** → Read: monitor GitHub Actions so agents can auto-fix CI.

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

## Which mode should you use?

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

Keep the **GitHub App token** default when you want per-user attribution and
no shared long-lived secret. Use a **PAT** when you want one credential to
administer centrally. Either mode requires its credential to be present.

The organization default applies unless a rig overrides it. When your
organization has a PAT saved, the create form offers a **GitHub
Authentication** section under **Advanced**, where you can pick a different
mode for that one rig.

> [!NOTE]
>
> Regardless of runtime mode, the GitHub App still governs which repositories are
> selectable in the UI. Connect it before creating rigs.

## Next steps

> [card] [Create a rig](https://docs.amika.dev/guides/create-a-rig.md)

> [card] [Inject credentials](https://docs.amika.dev/guides/inject-credentials.md)

> [card] [Authentication reference](https://docs.amika.dev/reference/auth.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.