Mirrors
Keep a repository in step with a copy on GitHub or another git server, or make it follow a remote, and fix a mirror that stops.
What a mirror is
A mirror keeps a repository in step with a repository on another host. It runs one way, in one of two directions.
| Direction | What it does | The repository |
|---|---|---|
| Push mirror | Sends branches and tags to the other host after every push here. | Stays writable. |
| Pull mirror | Fetches branches and tags from the other host into this repository. | Becomes read-only. |
A commit pushed straight to the other host is never copied back. The mirror stops on that branch instead, so nothing is overwritten without you. Issues, pull requests, reviews, CI runs, settings, secrets and webhooks stay on Sailfork.
Open a repository's Mirrors tab at https://status.sailfork.com/<owner>/<repo>/mirrors. Only repository admins see it and change mirrors: the owner of a personal repository, the owners of an organization, and a team with Admin on the repository. The routes are in Mirrors.
The page has three groups: Copies elsewhere for push mirrors, Pulled from elsewhere for pull mirrors, and Connected accounts. A mirror that stops never holds up the others.
Add a push mirror
- On the Mirrors tab, under Copies elsewhere, choose Add mirror.
- Pick the host: GitHub, GitLab, Bitbucket, Codeberg or Any git server.
- For GitHub, connect your account if it is not (see Connect GitHub), then pick the owner and repository name. Type a name that does not exist yet and Sailfork creates the repository, with the visibility you choose. It defaults to this repository's visibility.
- For any other host, paste the clone address and test the connection. An
httpsaddress needs a user name and a token with write access. Ansshaddress shows a deploy key to add on that host with write access. The key belongs to this repository only. - Choose what to send: every branch and tag, the default branch only, or the branches you pick, with patterns such as
release/*. Delete there what you delete here removes a branch or tag there when you delete it here, and is off by default. The form counts what the first push will carry. - Choose Start mirroring.
The first push goes out at once. After that every push here goes out about 10 seconds later. A push mirror has no polling: it sends when you push.
If the remote already holds commits, the form asks you to confirm replacing them before it starts. In an organization the replacement is written to the audit log as mirror.overwrite. GitLab, Bitbucket, Codeberg and other servers connect with a clone address and a token, or a deploy key over SSH. Only GitHub connects through a signed-in account.
Pull from a remote
Under Pulled from elsewhere, choose Pull from a remote and pick the source the same way. A repository has one pull mirror.
Important
The repository becomes a read-only copy. Its branches and tags follow the remote, and a push here fails with this repository is a mirror of <remote> and is read-only: push there instead until you remove the mirror. Branches in the repository that differ from the remote are replaced, and you confirm that first. Sailfork keeps a snapshot and a backup of each branch it rewrites.
- GitHub source. Pull requests, issues and releases come over too, and are read-only here. A private GitHub repository cannot feed a public repository here, so the code stays private: make the repository private first.
- Any other server. Paste the address. A public remote needs no token. For a private one, give a user name and a token with read access.
- After a migration. A repository moved from GitHub suggests the repository it came from. See Move from GitHub.
Sailfork fetches at once, then keeps checking. Sync now on the mirror's row fetches immediately.
Connect GitHub
GitHub mirrors go through the Sailfork GitHub App, so there are two steps, and both belong to the person adding the mirror.
- Connect your account. The form signs you in to GitHub to list the accounts and organizations you can reach, then returns to the form. The same connection lets you sign in to Sailfork with GitHub.
- Install the app. The app must be installed on the GitHub account or organization that holds the repository. It asks to read code in the repositories you pick, to write contents in them to push branches and tags, and to create a repository when the one you name does not exist. It never asks for more. Choose Grant access on GitHub in the form, or Install on GitHub under Connected accounts.
Under Connected accounts, each GitHub installation shows whether it covers every repository or only selected ones. Choose Update access to change that on GitHub. With selected repositories, add the one you want to mirror before you add the mirror.
| Owner | What to know |
|---|---|
| Personal GitHub account | You install the app on your own account. |
| GitHub organization | An owner of that GitHub organization installs or approves the app. If you are not one, GitHub asks them. They can also unsuspend it from Update access. |
| A Sailfork organization | Only organization owners and team admins manage mirrors. The form uses the GitHub account you connected, and the mirror records the installation it uses. |
Disconnecting an account under Connected accounts stops every mirror that pushes with it.
Webhook or polling
A pull mirror learns about new commits one of two ways.
- GitHub webhook. The GitHub App tells Sailfork about a push, and the mirror fetches at once. A fetch never accepts an older value than the webhook announced, so a lagging GitHub replica does not roll a branch back. It tries again on the next check.
- Polling. Every pull mirror also checks about every 10 minutes, from any host. This is the only way for a server other than GitHub, and the safety net when a webhook is missed. A remote that has not changed for a day is checked about every 30 minutes, and goes back to the shorter interval once it changes.
When a mirror stops
The row shows why, and what to choose.
| State | What happened | What to do |
|---|---|---|
| In sync | Nothing to do. | None. |
| Paused | You paused it, or the server did and says why. | Resume. |
| Expired | The GitHub authorization ran out. The mirror misses pushes until you fix it. | Reauthorize. |
| Disconnected | The account behind it was disconnected. | Connect the host again. |
| Cannot reach the repository | The app lost access, or was suspended. | Update access, or Grant access when no installation covers it. |
| Held (diverged) | The remote has commits Sailfork does not on that branch. Nothing was overwritten, and other branches keep mirroring. | Resolve: Import as branch or Overwrite this ref. |
| Refused | The remote refused a branch, with its reason. Other branches keep mirroring. | Fix the cause there. It retries when the branch changes. |
A mirror that has stayed in a bad state for more than 4 hours shows Stuck since on its row. You can also get a notice when one stops: see Notifications.
Import as branch brings the remote's commits into a branch named <host>-diverged/<branch>, from which you can open a pull request. Overwrite this ref replaces the remote's branch, asks you to type the repository name, and keeps a copy first that you can restore. If the remote moved again since it was checked, nothing is overwritten and you confirm again.
A pull mirror that sees a branch or tag deleted or rewritten keeps the old value under refs/sailfork/backup/. It pauses instead of continuing when the remote no longer has its default branch, or when more than a fifth of the branches and tags vanish at once. Choose Resume to accept the deletions.
Common refusals when adding one:
| Message | Meaning |
|---|---|
Connect GitHub first. | No GitHub connection yet. |
Grant the Sailfork app access on GitHub first. | The app is not installed where you chose. |
Your GitHub account cannot push to <owner>/<repo> | The account you connected has no write access to that repository. |
<owner>/<repo> does not exist on GitHub, or the Sailfork app was not given access to it | A pull source that is missing, or not covered by the installation. |
This repository already mirrors there. | The same destination is already set up. |
Pause and remove
On the mirror's row, Pause holds it and Resume restarts it. Remove mirror ends it. The copy on the other host stays, and what a pull mirror fetched stays here.