> ## Documentation Index
> Fetch the complete documentation index at: https://docs.replo.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Git Authentication Reference

> Configure authentication for a coding client, local Git checkout, or CI job.

Use this reference when following the [local setup checklist](/git/overview#setup-checklist-for-coding-clients), 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.

<Steps>
  <Step title="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](/mcp/overview), 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.
  </Step>

  <Step title="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.

    ```bash theme={null}
    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:

    ```bash theme={null}
    set -a
    source replo.env
    set +a
    ```

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

    ```bash theme={null}
    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:

    ```bash theme={null}
    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.
  </Step>

  <Step title="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.

    ```bash theme={null}
    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`.
  </Step>

  <Step title="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.

    <Tabs>
      <Tab title="Basic">
        Configure a credential helper for `git.replo.app`. The username is
        `token`, and the API key is the password.

        ```bash theme={null}
        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:

        ```bash theme={null}
        git ls-remote "$REPLO_GIT_URL"
        git clone "$REPLO_GIT_URL"
        ```
      </Tab>

      <Tab title="Bearer">
        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:

        ```bash theme={null}
        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`.
      </Tab>
    </Tabs>
  </Step>

  <Step title="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.

    ```bash theme={null}
    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](/git/overview#branches-pushing-and-publishing)
    before you push.
  </Step>
</Steps>

`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](/git/help).

<Warning>
  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.
</Warning>

## 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](/mcp/skills):

```bash theme={null}
npx skills add replohq/skills --skill local-development
```

For tools without that installer, copy [its `SKILL.md`](https://github.com/replohq/skills/blob/main/skills/local-development/SKILL.md).

## Next steps

<CardGroup cols={2}>
  <Card title="Understand Git access" icon="shield-check" href="/git/overview">
    Review authentication, scopes, and project permissions.
  </Card>

  <Card title="Troubleshoot Git" icon="wrench" href="/git/help">
    Fix the remote errors returned by `git.replo.app`.
  </Card>
</CardGroup>

[Back to Git overview](/git/overview) · [Troubleshoot Git](/git/help)