Sync with GitHub#

Your repository stays public on GitHub. Outside people open issues and pull requests there. Your team wants to read, review and merge on TanStack Source, and not miss anything that happens on GitHub.

GitHub sync keeps the two the same. New issues, pull requests and comments on GitHub come here in seconds. What people do here on those items goes to GitHub, under each person's own GitHub account.

Before you start#

To turn on sync, you need:

• A repository imported from GitHub with its issues and pull requests. See Import from GitHub.
• Admin access to the repository here and on GitHub.
• If your GitHub organization limits OAuth apps: an organization owner who approves the OAuth app of this site.

If the settings say "Import the repository again to turn on sync", do that import again. The first import did not keep the GitHub ids that sync needs.

1. Connect GitHub#

Each person who acts here on items from GitHub does this step once.

1. Open Connected accounts.
2. If the repository is private on GitHub, turn on Private repositories too under GitHub sync.
3. Click Connect GitHub for sync, then accept on GitHub.

If you already sign in with GitHub, connect the same GitHub account. Another account is refused.

What GitHub gives this site:

• Access: public_repo and workflow, or repo and workflow with Private repositories too. A push that changes .github/workflows/ needs workflow.
• The token: the server keeps it encrypted and never shows it. Disconnect deletes it here and revokes it on GitHub.

2. Turn on sync#

1. Open the Settings of the repository.
2. In GitHub sync, type the Release branches, for example main, alpha. The default is the default branch.
3. Turn on Sync with your GitHub repository.

You are now the sync owner. Your token creates the webhook on GitHub and reads GitHub for changes that a webhook missed.

For a new import, turn on Keep in sync with GitHub on the import form. Sync turns on when the import is done.

From a terminal:

src github-sync enable --branches main,alpha
src github-sync status
src github-sync disable

REST and MCP have the same calls. See /llms.txt on the site.

What goes where#

Issues and pull requests:

What	GitHub to here	Here to GitHub
Items opened on GitHub	Yes, with their GitHub numbers	Already there
Items opened here	Already here	No. They stay here.
Comments, reviews, line comments and replies	Yes	Yes, from people
Title and body edits, close and reopen, labels, assignees, resolved threads	Yes	Yes, from people
Notes on assignees	No. GitHub has none.	No. They stay here.
Comment edits and deleted comments	Yes	No. You cannot do these here.

New open items from GitHub are screened before they show, as the import screens them.

Code:

What	GitHub to here	Here to GitHub
Release branches	Yes, fast-forward only	Yes, fast-forward only
The code of GitHub pull requests (refs/pull/<n>/head)	Yes	No
Tags	Yes	No
Other branches	No	No

Who can act on items from GitHub#

• People who connected GitHub: the action goes to GitHub first, under their GitHub account. If GitHub refuses it, nothing changes here, and you see the reason from GitHub.
• People who did not connect: refused, with a link to connect.
• Agents: their comments and reviews stay here, with an Only here mark. Agents cannot close, reopen, label, rename, edit, resolve threads on, or merge an item from GitHub.

You need the permission on GitHub as well as here.

GitHub shows your text as you wrote it. So the editor warns you when your text links to this site, or names an item number from #100001 up.

Merge#

• A pull request from GitHub: Merge here merges it on GitHub with your token. The required checks, reviews and merge methods of GitHub apply. Then the base branch comes down. Its base must be a release branch.
• A pull request opened here, into a release branch: the merge commit goes to GitHub first, with your token. It has your GitHub noreply email.
• A git push to a release branch: goes to GitHub first, with your token.
• Agents cannot merge or push into a release branch.

The branch rules of GitHub apply to these pushes. If your main on GitHub refuses direct pushes, add the people who merge here to the bypass list of that rule.

Item numbers#

• While sync is on, new items here get numbers from 100001 up. GitHub never reaches those numbers, so #123 is the same item on both sides.
• While sync is off, new items get the next number again, and skip numbers that are in use.
• If the number of a GitHub item is in use here, the item gets a number from 100001 up. Its page shows "(GitHub #7)", and the sync settings count these items.

When something goes wrong#

The GitHub sync section shows the time of the last webhook and of the last catch-up, with a warning for each problem.

• The histories of a release branch split. Sync stops moving that branch, and never force-pushes. Make the two histories the same again by hand. After the next sync, the warning is gone.
• GitHub's branch moved before your merge. Wait for sync to bring it down, then merge again.
• A tag here points at another commit than on GitHub. The tag stays, with a warning.
• The token of the sync owner stops working, or they are no longer an admin. Sync pauses. Another admin clicks Take over.
• The rate limit of GitHub is used up. Sync waits, then goes on.

A catch-up runs every 5 minutes, so a missed webhook costs at most a few minutes.

Turn sync off#

Turn off Sync with in the settings, or run src github-sync disable. The webhook on GitHub is deleted, and new items get normal numbers again. Everything here stays. When you turn sync on again, it goes on from where it stopped.

Not synced#

• Discussions. TanStack Source has no discussions yet.
• Reactions, milestones and the draft state of pull requests.

Done#

Your team works on TanStack Source. Outside people keep using GitHub, and they see the replies, reviews and merges of your team under each person's own GitHub account.