# Import and sync from GitHub

Bring repositories from GitHub into GitCafe with their issues, pull requests,
reviews and comments, and optionally keep both sides in sync. Imports use the
GitCafe GitHub App, including for public repositories. GitHub is optional:
repositories created in GitCafe need no GitHub account.

## What syncs

An imported repository keeps receiving changes from GitHub. Two-way sync also
writes GitCafe changes back to GitHub.

| What                                     | One-way (default) | Two-way     |
| ---------------------------------------- | ----------------- | ----------- |
| Branches and tags                        | From GitHub       | Both ways   |
| Issues and pull requests                 | From GitHub       | Both ways   |
| Reviews and comments                     | From GitHub       | Both ways   |
| Labels, milestones, assignees, reactions | From GitHub       | Both ways   |
| Checks and commit statuses               | From GitHub       | From GitHub |
| Releases                                 | Not synced        | Not synced  |

GitHub Actions results arrive as checks. Images in conversations are linked,
not copied; see [images and attachments](https://staging.git.cafe/docs/integrations/github-sync.md#images-and-attachments).

## Create an account with GitHub

On the sign-up page, choose **Sync with GitHub** and approve GitCafe on GitHub.
If GitHub does not confirm your email address, verify it with the email
GitCafe sends before importing.

Your new account also gets the SSH and GPG keys on your GitHub profile, with
the default SSH access; keys GitCafe cannot use are skipped. Manage them
afterwards under [SSH keys](https://staging.git.cafe/docs/account/ssh-keys.md) and
[GPG keys](https://staging.git.cafe/docs/account/gpg-keys.md).

If your GitHub account is already linked to a GitCafe account, sign in to that
account instead; use **Reconnect GitHub** if the link needs refreshing.

## Import repositories

Open `/import/github`, or choose **Import from GitHub** on `/new`. The page
walks you through three steps.

1. **Connect GitHub**: authorize your GitHub account. You return to the import
   page afterwards.
2. **Choose repositories**: if the App is not installed yet, choose **Install
   GitCafe on GitHub**, pick the account or organization, and grant access to
   the repositories you want. An organization owner may need to approve. Back
   in GitCafe, the list refreshes; use **Check access** if it has not. Use
   **Modify repository access** to add repositories later, or **Use another
   account or organization** for another installation.
3. **Review and import**: choose the destination owner and name for each
   repository (up to ten at a time), check the settings and choose
   **Import N repositories**.

Imported repositories keep their GitHub visibility. Each repository shows its
own progress; **Sync status** opens the details. The code usually arrives
before the issues and pull requests.

Imports continue on the server if you close the page. Open the import page
again to see their progress, and use **Continue imports** if any stopped.

## Choose one-way or two-way sync

By default, an import copies from GitHub and never writes back. To keep both
sides in sync, select **Enable two-way sync, including writes to GitHub** for
the repository and choose which side wins when both change: **GitCafe wins** or
**GitHub wins**. Two-way sync needs write permission on GitHub.

After the import, changes made on GitHub arrive through the App's webhooks.
Pushes and merges made in GitCafe are sent to GitHub when two-way sync is on.

## Manage sync settings

Open the repository's **Settings → GitHub sync**. It shows the connected
GitHub repository, the sync direction, recent jobs and any changes still
waiting to reach GitHub. From there you can:

- **Renew authorization** when the connection asks for it.
- Change **When both sides change** for two-way sync.
- **Reconcile now** to check changes marked **Awaiting confirmation**, which may
  already be on GitHub.
- **Retry import** for an initial import that stopped.

If your GitHub authorization expired or was revoked, open **Account
connection**, reconnect GitHub, and try again.

## Merge pull requests that come from GitHub

Pull requests opened on GitHub, including from contributors' forks, appear in
GitCafe without the contributor doing anything. With two-way sync, choose
**Merge with GitHub** in the pull request's merge controls: GitHub performs the
merge with the method you pick, subject to its own checks and branch
protection, and GitCafe then picks up the result.

## Issue and pull request numbers

An imported issue or pull request keeps its GitHub number when that number is
free in GitCafe; otherwise it gets the next free number. When text is written
to GitHub, references like `#5` become full GitCafe links, so `Fixes #5` cannot
close an unrelated GitHub issue. Use full URLs when you refer to an issue on
the other site.

Issues closed on GitHub as duplicate or not planned appear as canceled in
GitCafe.

## Images and attachments

Images and videos from GitHub conversations display in GitCafe. When a comment
is written to GitHub, images attached in a public repository stay images;
images from a private repository become **View attachment in GitCafe** links,
so they stay private.

## When something is missing

- GitHub does not send events for reactions, so reactions made on GitHub
  update only when the related conversation changes again.
- If a change made on GitHub never arrives, open the App's webhook delivery
  history on GitHub and redeliver the failed event.
- A configured branch that has not synced for six hours is checked
  automatically.

To mirror a single branch with a server other than GitHub, use
[Git mirrors](https://staging.git.cafe/docs/repositories/git-mirrors.md).