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.

GitHub Actions results arrive as checks. Images in conversations are linked, not copied; see 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 and GPG keys.

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.