Backup and two-way modes

Open-beta availability

The GitHub App integration is live for invited preview testing. Backup-only is the first supported workflow and the planned default for open beta. Two-way writes remain a separate opt-in feature for eligible connections.

Each connection has one synchronization mode. Sync reacts to GitHub activity and also performs periodic reconciliation, so a delayed or reordered webhook does not decide the final repository state. The periodic check runs every 15 minutes.

Backup-only is the default

GitHub is authoritative in backup-only mode. Sync copies supported branch, tag, Git object, and Git LFS changes to Gitdown.

If Gitdown no longer matches the last successful checkpoint, Sync pauses the affected ref instead of overwriting an unexplained change. A pause appears in the connection, ref, and incident views with the next action available to the caller.

Gitdown branch protection still applies. The Git default branch is protected by default, and users may configure additional immutable branches. Sync never turns protection off or bypasses it.

Two-way requires a human

Only a human can enable two-way mode, reauthorize a GitHub installation, change provider authority, or disconnect a connection. Enabling two-way mode checks the current GitHub repository and Gitdown target again before the mode changes.

Two-way does not mean automatic merge, rebase, or force-push:

1. If exactly one side changed from the last checkpoint, Sync may advance the unchanged side.
2. If both sides changed incompatibly, Sync pauses that ref.
3. A human or authorized agent resolves the Git history outside Sync.
4. The caller records the chosen resolution and resumes only after the updated graph is safe.

Agents may acknowledge, propose a resolution for, retry, or safely resume an incident only when their repository grant includes the matching Sync capability. Agents cannot enable two-way mode, replace installation authority, or disconnect a connection.

Deletes, rewrites, and protected branches

An uncontested delete or rewrite follows the authoritative side only when the other side still matches its checkpoint. If both sides moved, Sync opens an incident instead of choosing a winner.

Gitdown rejects a rewrite or deletion of an immutable branch. Sync reports the policy pause and waits for an authorized user to decide whether to change the branch policy or change the proposed Git history. Disabling branch immutability is a separate, audited Gitdown action; Sync cannot perform it.

When a destructive change is accepted, displaced history remains retained by Gitdown for recovery and forensic review. See conflicts and incidents for the public recovery workflow.