GitHub & Git

Amp uses Git to bring your code into an orb and to get the agent’s changes back out. For repositories on GitHub, Amp signs in as you through a GitHub App connection. The agent can then clone private repositories, push branches, open pull requests, and read CI status, and you never have to create or paste a token. This page explains how the connection works, what Amp uses it for, and how commits made in orbs are attributed and signed.

Connect GitHub

Open Settings → Integrations and click Connect GitHub.

GitHub walks you through two steps:

1. Authorize Amp. This links your GitHub account to your Amp account. Amp uses the authorization to act as you when it talks to GitHub.
2. Install the Amp app. Pick the account or organization that owns your repositories, then choose All repositories or Only select repositories. Amp can reach exactly the repositories you select here, and only if your own GitHub account can reach them too.

If you already installed the app, for example because a teammate set it up for your organization, GitHub skips the second step. If your organization requires approval for third-party apps, an organization owner has to approve the installation before Amp can see its repositories.

Once connected, the card shows your GitHub login. Click the info icon to see which accounts the app is installed on and whether it covers all or selected repositories.

• Configure opens the app installation on GitHub, where you add or remove repositories.
• Re-authenticate appears when the connection has expired or was revoked on GitHub. Click it to sign in again; your repository selection stays as it is.
• Disconnect deletes the token Amp holds for you. It does not uninstall the app from GitHub. To remove the app itself, uninstall it from your GitHub application settings.

What Amp Uses the Connection For

• Creating projects. The New Project dialog lists the repositories your connection can reach. See Projects.
• Cloning into orbs. Before a new orb starts, Amp checks that your connection can reach the project’s repository and then clones it into the orb.
• Pushing and pull requests. git push and gh in the orb run as you. Pushes, branches, and pull requests show up on GitHub under your account.
• Commit, pull request, and CI details in threads. When the agent mentions a commit or pull request, the thread shows a preview with its status. Puck uses the same connection to check CI for you.
• The Librarian. The Librarian subagent reads your private repositories through your connection, in addition to all public code on GitHub.

Public GitHub repositories clone into orbs without a connection. Everything else on this list needs one.

How Orbs Authenticate to GitHub

Amp does not place a long-lived token in the orb. When the orb starts, Amp clones the repository into /home/user/workspace/repo with a shallow, single-branch clone. The credential for that clone applies only to the clone command and is discarded afterwards.

After that, whenever the agent runs a Git command that talks to GitHub, Git asks a credential helper, and the helper asks Amp for a short-lived token for your account. This means:

• The agent can fetch, push, and clone any repository on github.com that your connection can reach, not only the project’s repository.
• The gh CLI is preinstalled and gets its token the same way, so gh pr create and gh run view work without gh auth login.
• SSH URLs such as git@github.com:owner/repo.git are rewritten to HTTPS, so SSH keys are not needed.
• Git caches the token in memory for five minutes. It is never written to disk and never included in the project snapshot that later orbs start from.
• Branch protection rules and organization permissions apply exactly as if you had pushed from your own machine.

Threads that run on a runner or in a local CLI session use the Git configuration and credentials of that machine. Amp does not inject credentials there.

Commit Identity

A Git identity is the name and email that appear as the author of the commits the agent makes in orbs. Manage yours under Settings → Signing Keys → Git Identities. Your Amp account identity is available by default. To commit under another name and email, click Add Identity. Amp sends a verification link to that email, and the identity becomes usable once you confirm it.

Your Personal Default applies to your personal projects. To use a different identity for one project, choose it under Git Identity on that project’s page.

For workspace projects, workspace admins choose one policy for the whole workspace under Workspace Settings → Projects:

• Amp makes Amp <amp@ampcode.com> the author and adds the thread creator as a co-author through a Co-authored-by: trailer.
• Amp Account uses each thread creator’s Amp account identity.
• User Choice lets each member pick one of their verified identities.

When you are the author, the agent adds a Co-authored-by: Amp <amp@ampcode.com> trailer to mark the commit as made with Amp. To leave it out, set AMP_DISABLE_AMP_COAUTHOR_TRAILER=1 as a personal, project, or workspace environment variable. Commits the agent makes through its shell also carry an Amp-Thread-ID: trailer with the URL of the thread, so anyone reading the Git history can open the conversation that produced the change.

Signed Commits

Amp can sign the commits the agent makes in orbs. Amp generates an SSH keypair for you and keeps the private key encrypted on Amp’s servers. Git in the orb calls Amp to sign each commit, so the private key never enters the orb.

Open Settings → Signing Keys and turn on Sign Git Commits in Orbs. Amp signs a commit only when the selected Git identity uses an email you have verified, so commits made under the Amp identity are not signed.

For GitHub to show the commits as Verified:

1. Click Copy Public Key on your default keypair.
2. Open github.com/settings/ssh/new.
3. Set Key type to Signing Key, paste the key, and save.

GitHub also requires that the committer email is a verified email on your GitHub account.

Workspace Controls

Workspace admins can turn the GitHub integration off for the whole workspace in Workspace Settings → Integrations. The card also shows how many members have connected their GitHub account.

When the integration is off, members cannot connect GitHub, orbs cannot clone private GitHub repositories, and threads do not show commit or pull request previews. Existing connections stop working until an admin turns the integration back on.

Each member connects GitHub from their own personal settings. There is no shared workspace token, so every member only ever gets access to the repositories their own GitHub account can see.

Other Git Hosts

The GitHub connection is only for github.com. Other repositories work like this:

• Amp-hosted repositories. Choose Start From Scratch when you create a project and Amp hosts the repository for you. No setup is needed.
• Public repositories on other hosts. Paste the HTTPS URL when you create the project. Amp clones it without credentials.
• Private repositories on other hosts. The orb needs credentials to clone and push. See Configure Git.

GitHub Enterprise Server is not supported.

Troubleshooting