Repo-local Forgejo/GitHub fast-follow with fallback PR convergence #565

New issue

Open

opened 2026-07-16 05:01:31 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-07-16 05:01:31 +00:00

Owner

Ownership

Each participating repository carries a Forgejo workflow and a GitHub workflow.
Both workflows run on a default-branch push, support manual dispatch, and have a scheduled fallback for missed events.
A shared, versioned implementation owns the reconciliation algorithm. Repo-local wrappers own triggers, counterpart identity, credentials, branch policy, and rollout readiness.
Infrastructure may fan the wrappers out, but infrastructure runs no fleet-wide reconciliation job.

Reconciliation contract

For the configured default branch:

Equal tips: no-op.
One tip is an ancestor of the other: fast-forward the older side with a normal push.
The direct push is rejected by branch protection: create or update a synchronization PR.
Histories diverge: create or update that same synchronization PR.
The PR conflicts: leave both default branches untouched and report the blocked PR.
The PR merges: the resulting commit contains both histories, and the peer fast-forwards on the next event.
A push race: refetch once, recompute the graph, and fail closed if state remains ambiguous.
A mirrored push triggers the peer workflow, which observes equal tips and exits without looping.
Tags are append-only. A same-name tag with different targets fails closed.

The implementation never force-pushes, deletes refs, or synthesizes an unreviewed merge directly on a default branch.

PR convergence

Both workflows must choose one deterministic fallback destination so simultaneous divergence cannot create reciprocal PRs.

Default merge home: Forgejo.
Repo-local override: GitHub, including GitHub-canonical repositories such as homebrew-tap.
Use a stable synchronization branch and update one existing PR instead of opening duplicates.
Existing repository checks and merge policy decide whether the PR waits for Kai or uses configured auto-merge.

Credentials

Each workflow receives a credential scoped to its counterpart repository.
GitHub access uses the existing GitHub App short-lived installation-token path.
Forgejo access uses a repo-scoped automation identity rather than a fleet-wide push token.
Neither workflow prints credentials or reads generated runner registration files.

Rollout

A repository becomes dual-writable only after both wrappers, counterpart credentials, branch protection, and a clean round-trip pilot are present. Rollout can proceed repository by repository without a fleet cutover.

Done

A pilot repository fast-forwards in both directions.
A protected-branch rejection produces exactly one fallback PR at the configured merge home.
A deliberate divergence converges through that PR without force-updating either side.
A missed push event is repaired by the scheduled fallback.
The implementation documents failure reporting, credential rotation, and per-repo adoption.
Infrastructure owns an idempotent rollout for eligible repositories.

Centralized fleet mirroring is being removed under infrastructure#365 before repositories become writable from both Forgejo and GitHub. Replace it with repository-owned reconciliation that follows a push quickly when histories permit and uses the normal pull-request gate when they do not. ## Ownership - Each participating repository carries a Forgejo workflow and a GitHub workflow. - Both workflows run on a default-branch push, support manual dispatch, and have a scheduled fallback for missed events. - A shared, versioned implementation owns the reconciliation algorithm. Repo-local wrappers own triggers, counterpart identity, credentials, branch policy, and rollout readiness. - Infrastructure may fan the wrappers out, but infrastructure runs no fleet-wide reconciliation job. ## Reconciliation contract For the configured default branch: - Equal tips: no-op. - One tip is an ancestor of the other: fast-forward the older side with a normal push. - The direct push is rejected by branch protection: create or update a synchronization PR. - Histories diverge: create or update that same synchronization PR. - The PR conflicts: leave both default branches untouched and report the blocked PR. - The PR merges: the resulting commit contains both histories, and the peer fast-forwards on the next event. - A push race: refetch once, recompute the graph, and fail closed if state remains ambiguous. - A mirrored push triggers the peer workflow, which observes equal tips and exits without looping. - Tags are append-only. A same-name tag with different targets fails closed. The implementation never force-pushes, deletes refs, or synthesizes an unreviewed merge directly on a default branch. ## PR convergence Both workflows must choose one deterministic fallback destination so simultaneous divergence cannot create reciprocal PRs. - Default merge home: Forgejo. - Repo-local override: GitHub, including GitHub-canonical repositories such as `homebrew-tap`. - Use a stable synchronization branch and update one existing PR instead of opening duplicates. - Existing repository checks and merge policy decide whether the PR waits for Kai or uses configured auto-merge. ## Credentials - Each workflow receives a credential scoped to its counterpart repository. - GitHub access uses the existing GitHub App short-lived installation-token path. - Forgejo access uses a repo-scoped automation identity rather than a fleet-wide push token. - Neither workflow prints credentials or reads generated runner registration files. ## Rollout A repository becomes dual-writable only after both wrappers, counterpart credentials, branch protection, and a clean round-trip pilot are present. Rollout can proceed repository by repository without a fleet cutover. ## Done - A pilot repository fast-forwards in both directions. - A protected-branch rejection produces exactly one fallback PR at the configured merge home. - A deliberate divergence converges through that PR without force-updating either side. - A missed push event is repaired by the scheduled fallback. - The implementation documents failure reporting, credential rotation, and per-repo adoption. - Infrastructure owns an idempotent rollout for eligible repositories.

coilyco-ops added the

priority

label

2026-07-16 05:01:31 +00:00

coilyco-ops referenced this issue from a commit

2026-07-16 05:04:48 +00:00

chore: retire centralized repository mirroring

coilyco-ops added

autonomy

async-consult

priority

and removed