# Move from GitHub

Import repositories from GitHub with their history, issues and pull requests, keep a mirror in sync, and see what happens to your Actions workflows.

Sailfork reads your repositories from GitHub and copies them over. Nothing changes on GitHub until you switch a repository, and then only what you choose.

## What moves and what does not

| Item | Moves | Note |
| --- | --- | --- |
| Branches and tags | Yes | Every commit with its authors, dates and signatures, so commit hashes stay the same. Refs such as `refs/pull` stay behind. |
| Pull requests | Yes | With their reviews and comments. |
| Issues | Yes | With their comments. Every label (name and description) and milestone comes along, including ones no issue uses. Sailfork labels have no colors. |
| Releases | Yes | With their asset files. If a release on Sailfork already uses a tag, GitHub's release for that tag is left out. |
| People | Partly | Commits keep their authors. Issue, comment and review authors are matched to Sailfork accounts by email. You can match the rest by hand, and the others stay as GitHub names. |
| Visibility | Your choice | Keep it as on GitHub, or land everything private. |
| Actions workflows | Files only | The files come along. See [workflows after the move](#workflows-after-the-move). |
| Git LFS files | Yes | Every version the history points at. A file over the LFS limits is named on the move page. |
| Branch protection and rulesets | Yes, once | Copied when the copy is first made, and never over a rule you already set here. Protecting against force pushes and deletion, requiring a pull request, required checks, code owner reviews, who may push, and the merge queue all move. What has no Sailfork match, such as a count of approving reviews, required signatures or excluded branches, is named on the move page. |
| Collaborators and teams | Yes, once | A personal repository invites GitHub collaborators who are on Sailfork. An org repository gets GitHub's teams with access, created by name if needed, with their members who already belong to the org. Only an org owner's move creates teams. Everyone left out is named on the move page. |
| Wiki | Yes | Copied into its own repository, `<name>-wiki`, since Sailfork has no wiki. A wiki with no pages makes nothing. |
| Secrets | Names only | GitHub never gives out secret values. Once the copy is ready, the move page lists every secret the workflows read and whether it is set. |
| Webhooks, deploy keys, stars, watchers | No | Create them again on Sailfork where you need them. |

Everything besides code is optional. When you start a move, each part has its own switch: issues and pull requests, releases, branch rules, people with access, LFS files and the wiki. Anything you leave out can be brought later, see [bring more later](#bring-more-later).

A single file over 1 GiB stops the copy. See [what you see while it runs](#what-you-see-while-it-runs).

## Before you start

You need three things.

- **A Sailfork account.** Signing in with GitHub creates one.
- **GitHub linked to your account.** Without it, the import answers `connect your GitHub account first`.
- **The Sailfork GitHub App installed** on the GitHub account or organization that owns the repositories. The app reads only. It cannot push, delete or change anything on GitHub.

The import also checks your own GitHub permissions. You can only pick a repository your GitHub account can read.

### Personal account or organization

Each destination has its own migration page, at `https://sailfork.com/<handle>/migration`.

- **Your own account.** Open `https://sailfork.com/<your-handle>/migration`. You can also bring your whole GitHub account there: profile fields and your contribution history, then your repositories.
- **An organization on Sailfork.** Any member of the organization can import into it. If the organization requires two-factor authentication and you have not set it up, the import is refused until you do.
- **A GitHub organization as the source.** To import its repositories, the Sailfork GitHub App must be installed on it. If you are not an owner there, GitHub sends the request to the owners. The organization shows up in the picker once one of them approves.

## Import a repository

### In the web app

1. Open `https://sailfork.com/migrate` and choose **Authorize GitHub**. Signed in already, it takes you to the migration page of your first organization, or your own if you have none.
2. Choose **Move repositories**.
3. Under **To**, pick your account or an organization.
4. Under **Repositories**, pick single repositories or a whole GitHub organization. You can start up to 200 at once, and you can rename each one.
5. Under **What comes along**, turn issues and pull requests on or off, and choose whether visibility is kept or everything lands private.
6. Under **After the move**, choose what happens to the GitHub original:
   - **Move to Sailfork, archive GitHub.** GitHub turns read-only when you switch. This needs admin access to the repository on GitHub.
   - **Move to Sailfork, keep GitHub updated.** After the switch, every push to Sailfork goes on to GitHub through a push mirror.
   - **Keep GitHub primary, mirror it here.** No switch. The copy becomes a read-only mirror of GitHub.
   - **Move to Sailfork, leave GitHub as is.** GitHub stays writable and stops getting updates.
7. Choose **Start moving**.

If a name is already taken on Sailfork and you did not rename it, the repository lands as `<name>-github`. If that is taken too, the import is refused.

### From the terminal

The CLI drives the same move. Install it from [the install page](https://sailfork.com/install); [the CLI guide](https://sailfork.com/cli) covers signing in.

```sh
sailfork migrate installations
sailfork migrate repos --org acme
sailfork migrate start acme/api acme/web --into acme-sailfork --after archive
sailfork migrate status
sailfork migrate switch <move-id> --after archive
```

`--after` takes the same four endings as the web app:

| `--after` | Web app label |
| --- | --- |
| `archive` | Move to Sailfork, archive GitHub |
| `mirror` | Move to Sailfork, keep GitHub updated |
| `pull` | Keep GitHub primary, mirror it here |
| `leave` | Move to Sailfork, leave GitHub as is |

`migrate start` also takes `--as` (one repository), `--private`, `--installation` and `--dry-run`. It has no flag for leaving issues out. Use the web app for that. `migrate orgs` lists the GitHub organizations and account an installation can read, and `migrate cancel <move-id>` stops a move and removes the copy made so far, as **Stop moving** does.

### Other hosts

From GitLab, Bitbucket, Azure DevOps or your own server, `https://sailfork.com/migrate` writes a script that clones and pushes every branch and tag, then compares the two sides. It moves code only. Create the empty repositories on Sailfork first.

## What you see while it runs

Each repository moves through these steps on the server:

1. **Waiting to start.** Up to 8 repositories copy at once. The rest wait.
2. **Code.** Branches, tags and history.
3. **Issues and pull requests.** Skipped if you left them out.
4. **Checking it matches.** Sailfork compares branches, tags, releases, pull requests and issues with GitHub. If something differs, it goes back and copies again. After 3 failed checks in a row it stops.
5. **Ready to switch.** The copy is complete. Your team keeps pushing to GitHub. Sailfork shows how many commits arrived there since the last copy.

Then you switch, and the last copy brings in whatever was pushed since. The repository moves to **On Sailfork**, and your choice for the GitHub original is applied. The move page lists repositories under **Stopped**, **Ready to switch**, **Copying** and **On Sailfork**.

The copy runs on the server. You can close the page or the terminal, and a refresh only reads the current state. To stop a move before the switch, choose **Stop moving**. That deletes the copy made so far.

### When something stops

What was already copied is kept, and a retry picks up where the copy stopped.

| What you see | What it means | What to do |
| --- | --- | --- |
| Retrying in a time | A step failed. It retries with a wait that doubles from 30 seconds up to 15 minutes. | Wait, or choose **Try now**. |
| Stopped after 8 failed tries | The step failed 8 times in a row. | Fix the cause, then **Try again**. |
| App removed from an organization | Sailfork lost access to that GitHub organization. All its moves stop together. | Choose **Reauthorize**. Each repository resumes. |
| GitHub app needs more access | The installation was never granted a permission the copy needs, such as issues, commit statuses or pull requests. | Accept the updated permissions on GitHub, then **Try again**. |
| A file is over the limit | One file is larger than 1 GiB. | Move it to Git LFS on GitHub, then **Copy again**. This rewrites history there, so hashes change. |
| The mirror could not be set up | You chose to keep GitHub primary, and the pull mirror failed. The copy is kept. | **Try again**, or pick another ending. |

From the terminal, `sailfork migrate status` shows each move as `done`, `working`, `retry` or `human`, and `sailfork migrate retry <move-id>` runs a stopped move again.

## Bring more later

Once a copy is ready, and any time after you switch, its page on the migration screen has **Bring from GitHub**. Tick the parts you want and press the button. It runs on the server, so you can close the page, and each part shows when it last came over.

- A part left out at the start comes for the first time. A part that came before comes again with GitHub's latest.
- Nothing made on Sailfork is replaced. An issue or pull request made here keeps its number, and a GitHub item with the same number is named under **Not copied**. Branch rules you set here stay as they are. After the switch the wiki repository is never overwritten, because its edits now happen here.
- You need read access to the repository on GitHub when you ask, and the Sailfork GitHub App must still be installed. If GitHub stops it partway, the page says why. Try again, or stop bringing.

From the terminal:

```sh
sailfork migrate bring <move-id> items,wiki
sailfork migrate bring <move-id> --drop
sailfork migrate start acme/api --without items,wiki
```

Over the API: `POST /api/migrate/moves/{id}/bring` with `{ "parts": ["items", "wiki"] }`. The parts are `items`, `releases`, `wiki`, `rules`, `access` and `lfs`. An empty list drops whatever is still waiting.

## Mirrors

A mirror keeps Sailfork and another host in step. Open a repository's **Mirrors** page at `https://sailfork.com/<owner>/<repo>/mirrors`. The full guide is [Mirrors](https://sailfork.com/docs/mirrors).

- **Push mirror (copies elsewhere).** Every push to Sailfork goes out to the other host within seconds. It works with GitHub, GitLab, Bitbucket, Codeberg or any git server. This is what **keep GitHub updated** sets up.
- **Pull mirror (pulled from elsewhere).** Sailfork fetches from GitHub into the repository, and the repository refuses pushes. A repository has one pull mirror. This is what **keep GitHub primary** sets up. For a GitHub source it also brings pull requests, issues and releases, read-only. It checks about every 10 minutes, or every 30 minutes once the remote has been quiet for a day, and **Sync now** fetches at once.

Mirrors run one way. A commit pushed straight to the destination is never copied back.

### When a branch diverges or is held back

- **Push mirror.** If the destination has commits Sailfork does not, that branch is held. Nothing is overwritten and other branches keep mirroring. Choose **Import as branch** to bring those commits in, or **Overwrite this ref** to replace them. Overwriting asks you to type the repository name, and Sailfork keeps a copy first. If GitHub refuses a branch, it shows the reason and retries when the branch changes.
- **Pull mirror.** A branch or tag that GitHub deletes or rewrites is kept under `refs/sailfork/backup/`. The mirror pauses if GitHub no longer has the default branch, or if it deleted more than a fifth of the branches and tags at once. Choose **Resume** to accept the deletions.
- **Access lost.** Without access to the GitHub repository, the mirror stops and shows **Update access** or **Reauthorize**.

### Stop mirroring

On the mirror's row, choose **Pause** to hold it and **Resume** to restart it. Choose **Remove mirror** to end it. The copy on the other host stays, and what a pull mirror fetched stays in your repository. Disconnecting an account on the same page stops every mirror that uses it.

To make a repository follow GitHub after you moved it, open its Mirrors page and choose **Pull from a remote**.

## Point your local clone at Sailfork

In each existing clone, change the remote:

```sh
git remote set-url origin https://sailfork.com/<owner>/<repo>.git
```

The move page shows the exact command for each repository, using an SSH address if the server offers one. For HTTPS, let git use your Sailfork sign-in:

```sh
sailfork auth setup-git
```

Add `--local` to write the helper to one clone instead of your global git config. Add an ed25519, ECDSA or RSA key (2048 bits or more) if you push over SSH. DSA keys are refused.

If you chose **keep GitHub primary**, keep pushing to GitHub. Sailfork refuses pushes to a pull mirror.

## Workflows after the move

The `.github/workflows` files come with the code, but nothing runs until your organization has compute. Sailfork runs workflows with nektos/act on a connected Depot account or an online Drydock host, and a repository without an organization gets no runs.

Once the copy is ready, the repository's Runs page shows a compatibility report. It reads your workflow files and lists what will not run here, what needs setup and what may fail. Secrets do not move, so add them in the repository settings.

> [!NOTE]
> Triggers, the `GITHUB_TOKEN` and secrets are covered in [CI](https://sailfork.com/docs/ci).

For other questions, see [Help](https://sailfork.com/help).

---

Every docs page: https://sailfork.com/llms.txt
