Skip to main content
A mirror 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.

​
Prerequisites

Before you start, make sure you have:
If the mirror commands are not available, update Entire.

​
Log In

Log in with the Entire CLI:
Confirm that your login is active:

​
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.
  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:
Check whether the repository already has a mirror or is available to onboard:
Create a mirror placement:
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:
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:

​
Clone the Mirror

Clone by repository path:
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:

​
Use the Mirror in an Existing Checkout

From an existing GitHub checkout, let Entire add the remote:
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:
--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:
Confirm that the entire remote uses an entire:// URL, with origin still on GitHub:
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:
Push the commit through the mirror:
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:
If you added the mirror as a separate remote, drop that remote instead and leave origin alone:
Either way this only updates your local checkout.

​
Remove the Mirror

When you no longer need the mirror, remove the server-side mirror placement:
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

Your entire binary may be older than the mirror commands. Update Entire, then try again.
If git push reaches the Entire mirror but GitHub rejects the forwarded push, check the Entire GitHub App permissions.Open GitHub installed apps, find Entire, review any pending permission update, and make sure the app can access the repository you mirrored.Then refresh your Entire login:
Do not use entire logout to refresh: it drops every saved login and ends your CLI sessions on other machines too.
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:
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:
See Git LFS for more detail.
If Git cannot reach the entire:// remote, confirm the placement and retry through the Entire CLI:
If it keeps failing, see git-remote-entire Diagnostics.