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. In the left sidebar, under Workspace Settings, open API Keys, then select Create API key.If you have connected the Replo MCP server, your coding agent can do this for you instead: ask it to call create_api_key, and have it write the key straight to REPLO_API_KEY without printing it.Give the key a clear name, select the project it can access, and grant repo.read for clone and pull. Add repo.write if the key also needs to push.Copy the key when Replo shows it. You cannot view the full key again.

Store the key in your environment

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 your site in Replo and click Site Settings. On the General tab, expand Advanced and copy the Git clone URL shown there. A connected Replo MCP server returns the same URL as clone_url from 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. The username is token, and the API key is the password.

git config --global credential.https://git.replo.app.helper \
  '!f(){ echo username=token; 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. 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 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.

Install the local development skill

Coding agents should install Replo’s local-development skill before they push. It covers setup, branches, reviewing before a push, and how pushing relates to publishing. It installs with the rest of the Replo agent skills:

npx skills add replohq/skills --skill local-development

For tools without that installer, copy its SKILL.md.

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

​Install the local development skill

​Next steps

Understand Git access

Troubleshoot Git

Install the local development skill

Next steps