GitHub authentication

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, 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, 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?

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.

​

Next steps