Mirror a GitHub Repository

A mirror is a synced, read-optimized copy of a GitHub repository, hosted on Entire’s Git network 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.

Prerequisites

Before you start, make sure you have:

• Entire installed
• Access to clone the GitHub repository you want to mirror
• The Entire GitHub App authorized for the repository

If the mirror commands are not available, update Entire from the updating guide.

Log In

Log in with the Entire CLI:

entire login

Confirm that your login is active:

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.
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:

export GH_OWNER="<owner>"
export GH_REPO="<repo>"

Create the mirror:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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

• unknown command "repo": Your entire binary may be older than the mirror commands. Update Entire from the updating guide, 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, find Entire, review any pending permission update, and make sure the app can access the repository you mirrored. Then refresh your Entire login:

  entire auth logout
  entire auth login

• 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:

  entire repo mirror create "github.com/$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:

  GIT_LFS_SKIP_SMUDGE=1 git clone "entire://aws-us-east-2.entire.io/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

• Git cannot reach the mirror: If Git cannot reach the entire:// remote, retry the command first:

  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.