DocsOpen app

GitHub App two-way sync (SYNC-3)

A Zuppo repository and a GitHub repository kept equal both ways through a GitHub App.

A Zuppo repository and a GitHub repository kept equal both ways through a GitHub App. Unlike the SYNC-1 mirror (one way, read-only on Zuppo), a synced repository stays writable on both sides: agents work on Zuppo, people keep using GitHub, and each side sees the other's work.

Setting it up

  • Register a GitHub App (Settings → Developer settings → GitHub Apps) with:
  • Repository permissions: Contents read and write (branches and tags), Pull requests read and write, Issues read and write (conversation comments), Checks read and write, Metadata read.
  • Webhook URL: https://<zuppo-api>/github/webhook, a webhook secret, and the events push, create, delete, pull_request, pull_request_review, pull_request_review_comment, pull_request_review_thread, issue_comment, check_run, check_suite.
  • Generate a private key (PEM) and note the App id and slug.
  • Install the App on the repository's owner and note the installation id.
  • Create the Zuppo repository (CreateRepo, same object format: SHA-1 for GitHub), then run:
sh
zuppo-apid serve --state ... --cache ... \
  --sync-github orgs/acme/repos/api=octo/api \
  --github-app-id 123456 --github-app-slug zuppo-sync --github-installation 7890 \
  --github-app-key app.pem --github-webhook-secret-file webhook-secret \
  [--api-base https://ghe.example/api/v3] [--sync-interval 1m]

The server signs a JWT with the App key (RS256, 9 minutes), exchanges it for an installation token (refreshed 5 minutes before it expires), and runs a sync cycle every --sync-interval and shortly after every webhook. The key never leaves the process; the token appears only in the Authorization header of API calls and in git's environment.

What is synced

ThingGitHub → ZuppoZuppo → GitHub
branches and tags (refs/heads/* except zuppo/*, refs/tags/*)ref store compare-and-swapgit push --force-with-lease
a pull request opened on GitHuban imported change (as SYNC-1: revisions, title, description, state, reviews, conversation comments, inline threads)—
a change opened on Zuppo—a pull request from branch zuppo/<change id>: draft when the change is, retitled/re-described with it, force-pushed with each revision, marked ready, closed when the change lands or is abandoned
reviews, conversation comments and inline threads on a Zuppo change's pull requestreviews (never counting toward approval) and findings on the change—
reviews by Zuppo people and agents—reviews by the App, with the reviewer and revision in the text (a COMMENT with the verdict in the text on the App's own pull requests: GitHub refuses approving one's own)
findings—line comments (an issue comment when the line is not in the diff); status and resolution changes as replies
check runsfrom other apps (CI) on the pull request's head: check runs on the revision, reported by the Appthe App's check runs (external_id = the Zuppo check run)

Rules

  • The side a change or pull request was opened on owns its revisions, title, description, base branch and open/draft/closed state; the other side adds reviews, comments, findings and check runs. An edit of an owned field on the other side is reverted by the next cycle and logged as a conflict; on Zuppo, writing a revision of (or marking ready) a change that came from GitHub is refused (PERMISSION_DENIED).
  • Refs merge three ways against the last value both sides agreed on: one side moved → copied; both moved, one a fast-forward of the other → the descendant; diverged → GitHub wins and the Zuppo tip is kept as refs/heads/zuppo-sync/conflict/<branch>/<12 hex> (and logged). A delete against an unchanged ref deletes; a delete against a move keeps the move.
  • No loops: what the App writes on GitHub is authored by <slug>[bot] and carries a hidden marker <!-- zuppo:<kind>:<name> -->; the import side drops the bot's items. What came from GitHub is marked external on Zuppo and never exported back. A write whose answer was lost is found again by its marker (or branch, or external_id) instead of being written twice.
  • Closed native pull requests: a pull request of a Zuppo change closed on GitHub is reopened first; its zuppo/<id> branch only moves while the pull request is open (GitHub refuses to reopen a pull request whose branch was force-pushed while it was closed). When GitHub refuses the reopen anyway (422), the change moves to a new pull request from the same branch (found or opened, then relinked) and a conflict is logged.
  • Healing: at most once per --sync-interval a cycle reads the head check runs of every open paired pull request (a lost check_run webhook), and a pull request a webhook named is read by the import even when its updated_at (whole seconds) equals the last import's. The sync's own reads are conditional (If-None-Match, an in-memory cache of at most 4,096 URLs and 32 MiB of bodies, oldest dropped first): an unchanged answer is a 304, which GitHub does not count against the rate limit.
  • Drift: every verify_every quiet cycles (10: about every 11 minutes at a 1-minute interval while nothing changes) the sync reads both sides in full and compares them — for N pull requests ⌈N/100⌉ list pages plus 4 listings each (reviews, line comments, conversation comments, head check runs; one more page per 100 items), mostly 304s when nothing changed. A non-empty report is logged (two-way sync drift) and what it names is read again by the next cycle; an empty one is logged too (two-way sync verified: no drift, at info). A verification that cannot read everything is asked for again after the next cycle.

Soak

scripts/ghsync-soak.sh --duration <seconds> runs the acceptance soak against a fake GitHub App (REST, GraphQL, signed webhooks, git): random edits on both sides, and after every round an independent drift oracle plus the sync's own report. The acceptance run is scripts/ghsync-soak.sh --duration 172800 (48 h). Each round goes quiet, verifies, and when the verification found drift goes quiet and verifies once more (healed_by_verification in rounds.jsonl); a round drifted when the second report or the oracle is not empty (drift_rounds in summary.json, which must be 0).

Chaos

scripts/chaos.sh runs kill -9 against a real zuppo-apid syncing with the same fake GitHub App (scenario sync_kill_apid, crates/zuppo-apid/tests/chaos_sync.rs): the server is killed right after a random GitHub write (applied, its answer lost) or at a random moment, started again on its state, the soak's edits and a person's pushes go on, and after the last kill the oracle and the server's own verification (the log lines above) must both say no drift, no pull request, review, comment or check run may be on GitHub twice, every acknowledged push must still be on both sides, and a settled server killed once more must write nothing to GitHub when it comes back.