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

# Get started with Git

> Create a scoped API key and connect to a Replo site repository.

Create a Replo API key, get the site's replo-git URL, and choose Basic or Bearer authentication.

## Before you begin

* Install Git.
* Ask a workspace administrator to create an API key if you cannot open **Settings** > **API Keys**.
* Decide whether you need read access or push access.

<Steps>
  <Step title="Create an API key">
    Open **Settings** > **API Keys**, then select **Create API key**. Give the key
    a clear name, select the project, 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_..."
    ```

    Do not print the variable or commit it to a file.
  </Step>

  <Step title="Get the replo-git URL">
    Ask the Replo agent for the site's replo-git URL, then store it in your
    shell for the commands on this page.

    ```bash theme={null}
    export REPLO_GIT_URL="https://git.replo.app/<repository>.git"
    ```
  </Step>

  <Step title="Configure authentication">
    Choose one setup. Basic works with current Git versions. Bearer is useful for
    CI, 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 key when 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">
        For a single Git command or a CI job, pass the bearer header without
        saving it to Git configuration. In CI, prefer this per-command form, or
        write any helper configuration with `git config --local` inside the
        checkout so nothing persists on the runner:

        ```bash theme={null}
        git -c "http.extraHeader=Authorization: Bearer $REPLO_API_KEY" \
          ls-remote "$REPLO_GIT_URL"

        git -c "http.extraHeader=Authorization: Bearer $REPLO_API_KEY" \
          clone "$REPLO_GIT_URL"
        ```

        With Git 2.46 or later, you can use the credential protocol's `authtype`
        support for repeated commands:

        ```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"
        ```

        Raw HTTP clients send the same standard header. A working key returns
        HTTP 200 and a response that starts with `# service=git-upload-pack`:

        ```bash theme={null}
        curl --fail \
          --header "Authorization: Bearer $REPLO_API_KEY" \
          "$REPLO_GIT_URL/info/refs?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 add --all
    git commit --message "Describe your change"
    git push origin main
    ```
  </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>

## Add this workflow as a skill

Copy this `SKILL.md` into a coding tool that supports reusable skills. Set `REPLO_API_KEY` and `REPLO_GIT_URL` in its environment before using it.

````markdown theme={null}
---
name: replo-git
description: Use when cloning, inspecting, updating, or pushing a Replo site repository through git.replo.app.
---

# Replo Git

Use Replo's Git endpoint for site repository operations.

## Required environment

- `REPLO_API_KEY` contains a Replo API key with the scopes required for the operation.
- `REPLO_GIT_URL` contains the site's replo-git URL. Ask the Replo agent for it when it is not set.
- `REPO_DIR` contains the local checkout path when a repository is already cloned.

## Safety rules

- Never put the API key in a URL.
- Never print, log, or commit the API key.
- Never persist an Authorization header in `.git/config`.
- Do not push unless the user asks you to push.

## Workflow

1. Confirm that `REPLO_API_KEY` and `REPLO_GIT_URL` are set without printing their values.
2. Verify access:

   ```bash
   git -c "http.extraHeader=Authorization: Bearer $REPLO_API_KEY" \
     ls-remote "$REPLO_GIT_URL"
   ```

3. Clone when no checkout exists:

   ```bash
   git -c "http.extraHeader=Authorization: Bearer $REPLO_API_KEY" \
     clone "$REPLO_GIT_URL" "$REPO_DIR"
   ```

4. For an existing checkout, pass the bearer header to every network command:

   ```bash
   git -C "$REPO_DIR" \
     -c "http.extraHeader=Authorization: Bearer $REPLO_API_KEY" fetch origin
   git -C "$REPO_DIR" \
     -c "http.extraHeader=Authorization: Bearer $REPLO_API_KEY" pull --ff-only
   git -C "$REPO_DIR" \
     -c "http.extraHeader=Authorization: Bearer $REPLO_API_KEY" push origin HEAD
   ```

5. If the remote says `Git authentication failed.`, ask for a valid, unrevoked key.
6. If the remote says `Repository not found.`, check the replo-git URL, project selection, required scope, and key creator's current project role. Do not infer whether the repository exists.
7. If the remote reports a rate limit, wait for the `Retry-After` interval before retrying.
````

## 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>