GitHub import and synchronization#

Open /import/github while signed in. Every GitHub import requires the GitCafe GitHub App, including imports of public repositories. Repository creation requires verified email and permission to create under the destination owner.

Create an account with GitHub#

Choose Sync with GitHub on the sign-up page and complete GitHub authorization in the same browser. If the return to GitCafe fails, follow the page's restart instructions and check that the browser allows cookies. If your chosen email address is not verified by GitHub, verify it using the email from GitCafe before importing repositories.

If GitHub is already linked to a GitCafe account, this flow cannot create a second account. Sign in to your existing account and use Reconnect GitHub on the GitHub connection page. The rejected signup does not replace the existing account, connection, or repository configuration.

Authorize your account and install the App#

The page guides you through Connect GitHub → Choose repositories → Review and import. Completed access steps are skipped. If you created your account with GitHub, your account authorization is already connected.

Choose Connect GitHub to authorize your account. You return to your original import or repository settings task in the same browser tab. Then, if no App installation is visible, choose Install GitCafe on GitHub. This opens GitHub in a separate tab. Select an account or organization and grant access to the repositories you want to import, including public repositories. An organization owner may need to approve the installation. Return to GitCafe; access is checked again when the page regains focus. Use Check access if it has not appeared yet.

An installed account shows Modify repository access instead of an Install prompt. Use it to add missing repositories, then return to GitCafe. Use another account or organization lets you add a separate installation. A suspended installation offers management on GitHub so you can restore it.

Use Reconnect GitHub for expired or revoked account authorization. Your selections and accepted imports are preserved; authorization alone does not grant missing repository access. If access discovery fails, use Retry access check; a failed read does not mean the App is absent.

Import from an installed account#

Select the GitHub account/installation and repositories available to it. Choose their destination owner and names. The selection holds up to ten repositories. Imported repositories retain their GitHub visibility.

By default, connected imports copy Git once and import supported issues, pull requests, reviews and comments without writing back to GitHub. To opt in, select Enable two-way sync, including writes to GitHub for that repository. Choose GitCafe wins or GitHub wins for changes made on both sides. Two-way sync requires the corresponding GitHub write authorization; connecting an account alone does not enable it.

Pull requests from GitHub forks#

Incoming pull requests from a contributor's GitHub fork appear in the destination repository without requiring the contributor to install GitCafe or import their fork. GitCafe fetches the pull request's commits through the base repository's GitHub PR reference; it does not acquire write access to the contributor's fork.

With two-way sync enabled and the required permissions, choose Merge with GitHub in the pull request's merge controls. The selected merge strategy runs on GitHub against the reviewed head commit, subject to GitHub checks and branch protection. GitCafe then synchronizes the merged state and Git history. A successful GitHub merge does not mean local synchronization has finished; check sync status if the changes have not arrived. Read-only imports do not enable merging or other writes to GitHub.

Progress and interrupted imports#

Choose Review import, check the destinations, visibility and sync settings, then use Import N repositories to start. Back to selection lets you change your choices before submitting. Each repository keeps its own progress and failure message. Sync status opens the destination's detailed progress. Git data can arrive before discussion import finishes; it does not mean every part of synchronization is complete.

After initial import, supported GitHub changes arrive through App webhooks. As a safety net, a mirror whose configured branch has not synchronized for six hours gets one conditional check of that branch, at most hourly; if GitHub moved, the change is pulled the normal way. Sync status shows the next check and the oldest pending pull. There is no recurring scan of other branches, discussions or reactions. Local Git pushes and merges queue synchronization when they commit. Queued work or GitHub rate limits can delay delivery; the browser does not need to remain open.

GitHub does not send reaction webhooks. Reactions are acquired during import and when related issue, pull request or comment observations are processed. Local reaction writes still synchronize, but reaction-only changes made on GitHub can remain stale until another acquisition of that discussion. Simply waiting or refreshing a page does not guarantee a new GitHub reaction read.

A webhook GitHub never delivers cannot be recovered by retrying a queued job. If a supported change is missing, inspect the App's webhook delivery history and redeliver the failed event. GitCafe deduplicates the delivery identity. Retained jobs with failed queue wakes or interrupted execution remain recoverable.

Submitted imports are retained on the server and restored when you open the import page in another tab. Unsubmitted selections remain in this tab. Once accepted, the server owns destination creation, Git copy, and discussion setup even if you leave the page. Continue imports or a repository's Continue control checks retained progress and resumes supported work. Do not assume closing the tab cancelled the import or that an uncertain response means the destination was never created.

Continuing can refresh authorization for a blocked initial Git job only before any Git effect has begun. It never replays an uncertain Git operation. Open Sync status and use its authorization renewal or reconciliation controls for jobs whose effects may already have occurred.

Repository sync settings#

To mirror a branch with another Git server, use Git mirrors.

Open Settings → GitHub sync at /<owner>/<repo>/settings/github. This dedicated page manages Git history alongside issues, pull requests, reviews, comments and discussion metadata. It shows the connected source, direction, Git and discussion status, recent jobs and writes awaiting settlement. Depending on the repository's state and your authority, it offers connection/reconnection, completion of initial sync setup, authorization renewal and reconciliation.

Use Renew authorization when the connection asks for it. GitCafe checks your current GitHub permissions before continuing sync. If the connection has expired or been revoked and cannot refresh, open Account connection, reconnect GitHub, and retry. Repository permissions still apply.

Initial Git work must finish before synchronization can be configured. Two-way mirrors expose When both sides change; changing the winner does not stop one-sided changes from syncing in either direction.

Older public imports without an App installation show App installation is required to finish this import. Install the App, then connect the same source through the existing repository's settings. This keeps the destination and Git history; it does not enable two-way writes. If only destination creation finished, connect the intended source to that existing destination rather than creating a second repository. Divergent branches and unsettled Git operations require reconciliation before recovery can continue.

A pending local change is not proof that GitHub received it. The page distinguishes Not delivered writes from those Awaiting confirmation. The latter may already be on GitHub; reconciliation reads the existing outcome. Use Reconcile now where offered to inspect the retained operation. Resolve reported conflicts, blocked jobs or authorization problems before assuming convergence. Retry import is offered only for an eligible blocked initial import with no unfinished Git operation.

Read-only issue and pull-request snapshot imports blocked by stale admission retry automatically, up to three total attempts with 15 minutes between stale failures. Each attempt checks current authorization again. Invalid payloads, revoked access, and jobs with recorded native or provider effects are not automatically replayed by this recovery path.

Stacks waiting for an imported GitHub pull request acquire that exact pull request and resume when its import publishes. A blocked dependency remains visible for recovery. Saving unchanged settings with current authorization does not start another inventory; reconnecting or recovering blocked authority still acquires the new configuration.

GitHub issues closed as duplicate or not planned appear as canceled in GitCafe. Completed closures appear as completed. The original GitHub closure reason is retained with the imported issue.

Unreferenced terminal job history expires after seven days. Pending work, retained recovery references, and uncertain external outcomes are preserved; expiry never treats an unconfirmed write as delivered. Import progress updates over the live connection, including when an earlier import remains blocked.

Issue and pull request numbers#

GitCafe and GitHub numbers can differ. An imported resource keeps its GitHub number when that number is free locally; otherwise GitCafe allocates the next local number. Sync uses the retained provider identity in both directions, not the displayed local number. Existing resources are never renumbered; the old number-repair operation is unsupported.

When exporting Markdown, shorthand such as #5 referring to an existing local issue or pull request becomes an explicit GitCafe link. This prevents Fixes #5 from closing an unrelated GitHub issue with that number. These source links do not automatically close GitHub issues. Cross-provider shorthand translation is not supported; use the full URL of the intended resource when writing on either site. Code, explicit links and qualified references remain unchanged.

Attachments#

Referenced GitHub images and videos render inside imported conversations. Videos have playback controls and do not autoplay. Private media still requires access to the GitCafe repository; the proxy does not expose GitHub credentials.

GitCafe keeps the Markdown stored locally unchanged. When an issue, pull request, comment, or review is written to GitHub, images attached to the same repository are rewritten using this server's canonical public origin. Public-repository images remain images. Private-repository images become View attachment in GitCafe links: opening one requires GitCafe access to the repository, and the attachment bytes are not copied to or made public on GitHub. Attachment-looking text in code spans or fenced code, and references to another repository's attachments, are left unchanged.