Git Authentication Reference

Use this reference when following the local setup checklist, configuring Git yourself, or running it in CI. For the local editing workflow, grant both repo.read and repo.write so edits can return to Replo. Any workspace member can create an API key.

Create an API key

If REPLO_API_KEY is already set with the repository scopes you need, skip to the next step.In Replo, open the project menu (the ⋮ button in the top bar) and choose Settings. Pick the key type:

User key for a coding agent on your machine, such as Codex or Claude Code. Under Account, open Git and select Create Git key. It reaches every project you can access with your current role. Choose Clone and push or Clone only, and when it expires. The page then shows a command for your computer that saves the key in Git’s password store, plus each site’s clone command. Once you run it, skip to Push a change.
Project key for CI and automation. Under Workspace, open API Keys and select Create API key. Select the projects it can reach and grant repo.read for clone and pull; add repo.write if it also needs to push. It can expire or last until you revoke it.

With the Replo MCP server, call create_api_key with your workspace ID, a name, type, projectIds, scopes and expiresInDays. type defaults to user: send projectIds: null, both repository scopes and a lifetime of 1–366 days. For type: "project", list the projects in projectIds; expiresInDays: null keeps the key until you revoke it. Follow the local-development skill (read it with the MCP server’s skills tool) to store secret as the password using git.protocol, git.host, and git.username, then clone a clone_url from list_sites.API callers use POST https://api.replo.app/v1/api-keys with the same fields, a bearer key with api_keys.write, and Replo-Api-Version: 2026-10-29. Older versions keep their single-projectId contract. Creating an 11th live user key revokes an unused key first, otherwise the least recently used one. Settings lists every key and lets its owner revoke it.Copy the key when Replo shows it. You cannot view the full key again.

Store the key in your environment

Use this step and the next two in CI, or when you configure Git yourself. On your own computer, the command Settings shows with a new user key saves it in Git’s password store instead: Keychain on macOS, Git Credential Manager on Windows, and Git’s store file on Linux.Set the key in your shell. Store it as a masked secret instead when you run Git in CI.

export REPLO_API_KEY="replo_sk_..."

Keep export. Git runs the credential helper as a separate process, and that process only sees exported variables. A plain REPLO_API_KEY=... line, or source-ing a file without export, leaves the helper with an empty password and Git reports Git authentication failed.If you keep the key in a file of KEY=value lines, export everything it defines while loading it:

set -a
source replo.env
set +a

Confirm that a child process can see the key without printing it:

sh -c 'test -n "$REPLO_API_KEY"' && echo "REPLO_API_KEY is exported"

Keep the exported key in the shell that runs Git. When you install or run a cloned site locally, remove the key only from that child command:

env -u REPLO_API_KEY pnpm install
env -u REPLO_API_KEY pnpm dev

Use the prefix each time you launch the dev server, including after a restart. The parent shell keeps the key for later Git commands.Do not print the variable or commit it to a file.

Get the replo-git URL

A site’s ID is its Git repository name. If you already have the site ID, build the supported clone URL directly without the dashboard or Replo MCP server, then store it in your shell for the commands on this page.

export REPLO_GIT_URL="https://git.replo.app/<site-id>.git"

Otherwise, open Settings > Account > Git in the site’s project and copy the clone command under Set it up yourself. A connected Replo MCP server returns an account-specific URL as clone_url from read-only list_sites.

Configure authentication

Choose one setup. Basic works with current Git versions. Bearer is useful for raw HTTP clients and environments that already use bearer credentials.

Basic
Bearer

Configure a credential helper for git.replo.app. Use the account-specific username from clone_url (or git.username when creating the key), and the API key as the password. Export that username as REPLO_GIT_USERNAME.

git config --global --replace-all credential.https://git.replo.app.helper ''
git config --global --add credential.https://git.replo.app.helper \
  '!f(){ echo "username=$REPLO_GIT_USERNAME"; echo "password=$REPLO_API_KEY"; };f'

The helper is scoped to git.replo.app and reads the exported REPLO_API_KEY each time Git runs. The empty helper on the first line stops a password manager such as macOS Keychain from answering for git.replo.app with an old key. Verify the connection, then clone:

git ls-remote "$REPLO_GIT_URL"
git clone "$REPLO_GIT_URL"

With Git 2.46 or later, use the credential protocol’s authtype support. The helper reads the exported key at runtime, so the credential does not appear in Git’s command-line arguments:

git config --global --replace-all credential.https://git.replo.app.helper ''
git config --global --add credential.https://git.replo.app.helper \
  '!f(){ echo capability[]=authtype; echo authtype=Bearer; echo "credential=$REPLO_API_KEY"; };f'

git ls-remote "$REPLO_GIT_URL"
git clone "$REPLO_GIT_URL"

In CI, write this configuration in the job’s temporary home, or use git config --local after checkout. Do not interpolate the key into git -c http.extraHeader=...; command-line arguments can be visible to other processes on the runner. Use the Basic helper on Git older than 2.46.Raw HTTP clients send the same standard header. Supply the value through the client’s secret-input mechanism rather than a command-line argument. A working key returns HTTP 200 and a response that starts with # service=git-upload-pack.

Push a change

Set a commit identity once if the machine has none, then commit and push. Pushing requires a key with repo.write; a read-only key receives Repository not found. on push.

cd <your-cloned-directory>
git config user.name "Your Name"
git config user.email "you@example.com"
git status --short
git add <path> [<path>...]
git diff --cached
git commit --message "Describe your change"
git push origin main

Stage only the paths you intend to push. The local dev server can generate root AGENTS.md and CLAUDE.md files for coding clients; leave them untracked unless you deliberately changed the site’s shared instructions.Pushing does not publish, but the next publish can include anything on main. See Branches, pushing, and publishing before you push.

git ls-remote prints the repository’s refs when the URL, key, scope, and project access are valid. Expect at least a HEAD line. If the command returns an error, use the Git troubleshooting guide.

Keep the key out of the replo-git URL. Use the credential helper or bearer header so the remote stored in .git/config stays safe to copy.

Read the local development skill

Coding agents should read Replo’s local-development skill before they push. It covers setup, branches, reviewing before a push, and how pushing relates to publishing. With the Replo MCP server connected, the agent reads it with the skills tool:

skills({ name: "local-development" })

See Agent skills for how Replo’s skills reach your client.

Next steps

Understand Git access

Review authentication, scopes, and project permissions.

Troubleshoot Git

Fix the remote errors returned by git.replo.app.

Back to Git overview · Troubleshoot Git

Git

Replo SDK

Full SDK Reference

Git Authentication Reference

Read the local development skill

Next steps

Understand Git access

Troubleshoot Git

​Read the local development skill

​Next steps

Understand Git access

Troubleshoot Git

Read the local development skill

Next steps