> ## Documentation Index
> Fetch the complete documentation index at: https://docs.entire.com/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) serves a GitHub repository from an EntireDB cluster while GitHub remains the upstream repository.

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](/installation#install-and-update-entire).

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

Check whether the repository already has a mirror or is available to onboard:

```bash theme={null}
entire repo mirror list --name "$GH_OWNER/$GH_REPO"
```

Create a mirror placement:

```bash theme={null}
entire repo mirror add "/gh/$GH_OWNER/$GH_REPO"
```

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

Write the repository as a `/gh/OWNER/REPO` reference. A bare `owner/repo` and a GitHub URL are both refused, with a message telling you the `/gh/` spelling to use instead. When more than one cluster is available, an interactive terminal offers them as a multi-select. A non-interactive command defaults to `aws-us-east-2.entire.io`. Entire waits until the initial GitHub clone is available.

To create the mirror in another region, name the cluster with `--cluster`:

```bash theme={null}
entire repo mirror add "/gh/$GH_OWNER/$GH_REPO" --cluster aws-eu-central-1.entire.io
```

When the initial clone is ready, the command prints a table of repository, region, status, and clone URL, followed by the `git clone` command for it.

Inspect the repository and its regional placements:

```bash theme={null}
entire repo view "/gh/$GH_OWNER/$GH_REPO"
```

## Clone the Mirror

Clone by repository path:

```bash theme={null}
entire repo clone "/gh/$GH_OWNER/$GH_REPO"
```

If the repository has placements in several regions, an interactive terminal prompts you to select one. Without a terminal, Entire falls back to `aws-us-east-2.entire.io` and errors if the mirror is not placed there. Pass `--cluster` to choose either way:

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

## Use the Mirror in an Existing Checkout

From an existing GitHub checkout, let Entire add the remote:

```bash theme={null}
cd "$GH_REPO"
entire repo remote add entire
git fetch entire
```

Entire resolves the repository from the checkout's existing remotes. If it has placements in several regions, an interactive terminal prompts you to select one. Without a terminal, Entire falls back to `aws-us-east-2.entire.io` and errors if the mirror is not placed there. Pass `--cluster` to choose either way.

This leaves `origin` on GitHub and adds `entire` alongside it. To send everyday Git commands through the mirror instead, repoint `origin`:

```bash theme={null}
entire repo remote add origin --override
```

`--override` is required for a name that already exists; without it the command refuses rather than repointing. Entire prints the URL it replaced, with credentials redacted, and that printout is the only record of it.

These commands only update the local checkout. They do not create or delete a mirror placement.

## Verify the Mirror

Fetch through the mirror:

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

Confirm that the `entire` remote uses an `entire://` URL, with `origin` still on GitHub:

```bash theme={null}
git remote -v
```

If you repointed `origin` with `--override` instead, plain `git fetch` goes through the mirror and `origin` is the `entire://` URL.

## 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 entire mirror-push-test
```

Use `origin` here instead if you repointed it with `--override`.

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 repointed `origin` with `--override`, set it back with plain Git:

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

If you added the mirror as a separate remote, drop that remote instead and leave `origin` alone:

```bash theme={null}
git remote remove entire
```

Either way 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 "/gh/$GH_OWNER/$GH_REPO"
```

On a terminal Entire offers the clusters the repository is mirrored on as a multi-select. There is no default, so a non-interactive run must name them with `--cluster`.

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

> **Unknown Command "repo"**
>
> Your `entire` binary may be older than the mirror commands. [Update Entire](/installation#install-and-update-entire), then try again.

> **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 login
> ```
>
> Do not use `entire logout` to refresh: it drops every saved login and ends your CLI sessions on other machines too.

> **Mirror Creation Takes a While**
>
> By default `entire repo mirror add` 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 add "/gh/$GH_OWNER/$GH_REPO" --no-wait
> ```

> **Cloning a Mirror with LFS Files Fails During Checkout**
>
> Mirrors do not currently support Git LFS. If the repository uses LFS, cloning the mirror fails during checkout with a `smudge filter lfs failed` error.
>
> As a workaround, point Git LFS at GitHub so that large file transfers go through GitHub, while regular Git operations keep using the mirror:
>
> ```bash theme={null}
> GIT_LFS_SKIP_SMUDGE=1 entire repo clone "/gh/$GH_OWNER/$GH_REPO"
> cd "$GH_REPO"
> git config lfs.url "https://github.com/$GH_OWNER/$GH_REPO.git/info/lfs"
> git lfs pull
> ```
>
> See [Git LFS](/guides/repositories/mirrors#git-lfs) for more detail.

> **Git Cannot Reach the Mirror**
>
> If Git cannot reach the `entire://` remote, confirm the placement and retry through the Entire CLI:
>
> ```bash theme={null}
> entire repo view "/gh/$GH_OWNER/$GH_REPO"
> entire repo clone "/gh/$GH_OWNER/$GH_REPO"
> ```
>
> If it keeps failing, see [`git-remote-entire` Diagnostics](/guides/repositories/troubleshooting#git-remote-entire-diagnostics).