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

# Mirror a GitHub Repository

> Bring an existing GitHub repository into Entire without moving your source of truth or changing your team's workflow.

A [mirror](/guides/repositories/mirrors) is a synced, read-optimized copy of a GitHub repository, hosted on [Entire's Git network](/guides/repositories/overview) in the region you choose.

Your team can keep pushing to GitHub as usual, while agents and selected users clone and fetch through an `entire://` URL.

This tutorial shows how to create a mirror, use it with Git, and switch your local checkout back to GitHub if you need to.

For a shorter command-line guide, see [Mirrors in CLI](/guides/repositories/mirrors-in-cli).

## Prerequisites

Before you start, make sure you have:

* [Entire installed](/installation)
* Access to clone the GitHub repository you want to mirror
* The [Entire GitHub App authorized](/guides/repositories/github-app-access) for the repository

<Tip>
  If the mirror commands are not available, update Entire from the [updating guide](/updating).
</Tip>

## Log In

Log in with the Entire CLI:

```bash theme={null}
entire login
```

Confirm that your login is active:

```bash theme={null}
entire auth status
```

## Check GitHub Access

Before you create or push through a mirror, confirm that the Entire GitHub App can access the repository.

1. Open [GitHub installed apps](https://github.com/settings/installations).
2. Find **Entire**.
3. If GitHub shows **Permission updates requested**, click **Review request** and approve the update.
4. Click **Configure** for Entire.
5. Choose **All repositories** or select the repository you want to mirror, then click **Save**.

## Create the Mirror

Choose the GitHub repository you want to mirror:

```bash theme={null}
export GH_OWNER="<owner>"
export GH_REPO="<repo>"
```

Create the mirror:

```bash theme={null}
entire repo mirror create "github.com/$GH_OWNER/$GH_REPO"
```

This registers the mirror on Entire. It does not change any local Git checkout.

The repository can be written as `owner/repo`, an HTTPS GitHub URL, or an SSH GitHub URL. By default, Entire creates the mirror on `aws-us-east-2.entire.io` and waits until the initial clone is available.

To create the mirror in another region, pass the cluster host as the second argument:

```bash theme={null}
entire repo mirror create "github.com/$GH_OWNER/$GH_REPO" aws-eu-central-1.entire.io
```

The command prints the mirror URL when it succeeds:

```text theme={null}
Registered mirror <mirror-id>
  entire://aws-us-east-2.entire.io/gh/<owner>/<repo>
  cloning. ready
```

## Clone or Add the Mirror Remote

To clone the mirror into a new checkout, use the URL printed by `entire repo mirror create`:

```bash theme={null}
git clone "entire://aws-us-east-2.entire.io/gh/$GH_OWNER/$GH_REPO"
```

From an existing clone of the GitHub repository, point the local `origin` remote at the mirror:

```bash theme={null}
cd "$GH_REPO"
git remote get-url origin
git remote set-url origin "entire://aws-us-east-2.entire.io/gh/$GH_OWNER/$GH_REPO"
git fetch origin
```

If you want to verify the mirror before changing the checkout's primary remote, add it temporarily as another remote:

```bash theme={null}
cd "$GH_REPO"
git remote add entire "entire://aws-us-east-2.entire.io/gh/$GH_OWNER/$GH_REPO"
git fetch entire
```

These commands only update your local `.git/config`. They do not create or delete the server-side mirror.

## Verify the Mirror

Run normal Git commands through the configured remote:

```bash theme={null}
git fetch
git status
```

At this point, your local checkout is using the Entire mirror for Git operations.

## Push Through the Mirror

Create a test branch, make a small change, then stage and commit it:

```bash theme={null}
git switch -c mirror-push-test
echo "Mirror test" >> mirror-test.txt
git add mirror-test.txt
git commit -m "Test mirror push"
```

Push the commit through the mirror:

```bash theme={null}
git push -u origin mirror-push-test
```

Entire forwards the push through the mirror to the upstream GitHub repository. Your GitHub write access, branch protection rules, and required checks still apply.

## Restore the GitHub Remote

If you pointed `origin` at the mirror and want to switch back to GitHub, set the remote URL back to your original GitHub URL:

```bash theme={null}
git remote set-url origin "git@github.com:$GH_OWNER/$GH_REPO.git"
```

This only updates your local checkout.

## Remove the Mirror

When you no longer need the mirror, remove the server-side mirror placement:

```bash theme={null}
entire repo mirror remove "github.com/$GH_OWNER/$GH_REPO"
```

Removing a mirror does not delete or rewrite the GitHub repository. It also does not change any local Git remotes you configured in `.git/config`.

## Troubleshooting

<AccordionGroup>
  <Accordion title="unknown command &#x22;repo&#x22;">
    Your `entire` binary may be older than the mirror commands. Update Entire from the [updating guide](/updating), then try again.
  </Accordion>

  <Accordion title="403: Write access to repository not granted">
    If `git push` reaches the Entire mirror but GitHub rejects the forwarded push, check the Entire GitHub App permissions.

    Open [GitHub installed apps](https://github.com/settings/installations), find **Entire**, review any pending permission update, and make sure the app can access the repository you mirrored.

    Then refresh your Entire login:

    ```bash theme={null}
    entire auth logout
    entire auth login
    ```
  </Accordion>

  <Accordion title="Mirror creation takes a while">
    The default create command waits for the initial clone to appear on Entire. For large repositories, that can take time.

    If you only need to register the mirror and check back later, use `--no-wait`:

    ```bash theme={null}
    entire repo mirror create "github.com/$GH_OWNER/$GH_REPO" --no-wait
    ```
  </Accordion>

  <Accordion title="Git cannot reach the mirror">
    If Git cannot reach the `entire://` remote, retry the command first:

    ```bash theme={null}
    git clone "entire://aws-us-east-2.entire.io/gh/$GH_OWNER/$GH_REPO"
    ```

    If it keeps failing, check your network connection and try again.
  </Accordion>
</AccordionGroup>