Skip to content

Forge and CIreference

Carrying patches on a fork: layout, drift checks and rebase gates

A downstream fork is upstream plus a short stack of your own commits, replayed every time upstream moves. This reference covers how that stack is laid out, how drift from upstream is detected, when a rebase may be trusted without a human, and what to check before the result is deployed. It is drawn from three forks on a self-hosted Forgejo: the OpenWrt build behind the SKS8300 switch, a patched rbw (the Bitwarden CLI), and the Fladder fork whose Windows releases are built by the Windows build VM.

Counts and timings were taken from the three repositories and their Forgejo Actions history on 2026-11-15; the Forgejo behaviour is cited from its documentation and, where noted, checked against run history.

  • One branch per fork, linear, rebased onto upstream and never merged. It is the Forgejo default branch, because scheduled workflows only run from there.
  • Fork-only files live under .forgejo/ plus one AGENTS.md. Upstream never writes there, so those files never conflict. Deleting an upstream file you merely want inactive is a conflict on every later upstream edit to it.
  • The stack’s size is the running cost: every commit is re-applied and compared on every rebase. On the OpenWrt fork, 3 of 93 commits touched upstream code before it was squashed to 4; the stops that were not real conflicts came from the other 90.
  • A clean rebase is not a deployable one. The OpenWrt auto-rebase of 2026-11-09 was patch-identical and built green, and was still skipped because upstream committed a fix to the new code it carried four days later.
ForkBranchUpstreamFork commitsDrift jobRebase
rbwpatcheddoy/rbw main8daily 01:00 UTC, reportby hand, sync-upstream.sh
FladderpatchedDonutWare/Fladder develop77daily 01:00 UTC, reportby hand, sync-upstream.sh
OpenWrtsks8300-edgeopenwrt main4 (93 before 2026-11-15)weekly, Monday 02:00 UTCautomatic to a candidate branch, deploy by hand

In the 8 weeks to 2026-11-15 upstream rbw main gained 0 commits, Fladder develop 51 and OpenWrt main 1873. rbw and Fladder carry application patches and a rebase is rare or small. An OpenWrt image takes about 26 minutes to build, and deploying it is a firmware flash that drops the house network several times, so the OpenWrt fork automates everything up to the flash.

upstream maindrift job(schedule)tracking issuereportcandidate branch+ candidate buildclean rebasereview must-read+ upstream past baseskip, waitfor next cycledeploy(RAM test, flash)gofork branch= deployedtag + move
  1. The scheduled drift job compares the fork branch with upstream main and writes its report to one tracking issue.
  2. If the rebase is clean it pushes the result to a candidate branch and dispatches the image build.
  3. A review reads the must-read commits and checks upstream main past the candidate’s base for fixes to code the candidate carries.
  4. Go: the candidate is deployed, tagged, and the fork branch moves to it. Skip: nothing moves and the next cycle produces a newer candidate.

The fork branch is upstream plus our commits, kept linear by rebasing. In each local checkout origin is upstream (fetch only) and fork is Forgejo. The OpenWrt checkout also sets remote.pushDefault=fork and push.default=current, so a plain git push goes to the fork.

The OpenWrt checkout tracks origin/main on purpose: scripts/getver.sh builds the image revision from the merge-base with the tracking branch, as r<upstream commits>+<fork commits>-<upstream sha>. The price is that git status reports the fork’s size and lag (“ahead 93, behind 259”), not unpushed work. Unpushed work is git rev-list --count fork/sks8300-edge..HEAD. The behind count only shrinks when an image is flashed and the fork branch moves to it; rebasing the deployed branch by hand to clear it would make the branch stop describing what runs on the switch.

Forgejo starts scheduled workflows only from the default branch1, so the fork branch is the repository’s default branch. On the OpenWrt fork, the copies of upstream main, master and the release branches left from the initial import have no .forgejo/ directory and would fall back to upstream’s workflows if anything were pushed to them.

rbw and Fladder keep every fork-only file under .forgejo/ - workflows and scripts - plus an AGENTS.md at the root. Upstream does not write to either path, so a rebase never touches them.

Forgejo reads .github/workflows only when .forgejo/workflows is absent2. Upstream’s GitHub workflows can stay in the tree untouched: rbw carries upstream’s .github/workflows/tests.yaml, and all 27 recorded runs of the rbw repository are its own .forgejo workflows. The OpenWrt fork instead deleted upstream’s ten .github/workflows files, and that deletion conflicted on the 2026-09-23 rebase when upstream edited them.

The OpenWrt fork predated the rule, and its stack showed what the alternative costs. Against the merge-base d6a91d867b, on 2026-11-15 before the clean-up:

Commits touchingCount
docs only (docs/, AGENTS.md)40
CI only (.forgejo/)10
operator scripts only (scripts/sks8300-*)8
the baked config overlay (files/) only5
upstream code (target/, package/), alone or mixed3
other mixes of the above, root scripts, .gitignore, .github deletions26
empty (a commit made only to trigger a CI build)1
total93

The net kernel delta of those 93 commits is 14 changed lines in two files: a 13-line hunk in the RTL83xx DSA driver and one device-package line. The image also needs the files/ overlay (the switch’s config is baked in so a first boot cannot put a default network on the trunk) and the CI and drift tooling. The rest - perf logs, research notes, plans, runbooks, the check, perf, upgrade and serial scripts - is operator material that the build never reads. On 2026-11-15 it moved to a separate operations repository, upstream’s .github/workflows were restored, and the fork was squashed to 4 commits: the driver patch, the device-package line, the overlay, and CI with the drift and build tooling (including the config deploy script, which pushes the overlay). The image revision went from r38000+93 to r38000+4 with byte-identical build inputs, and the old history stays reachable from an archive tag.

That material is cheap to write and costs on every cycle: each commit is one more patch to rebase and compare, and since the image revision counts fork commits, a week of notes moves the +N suffix. It has also stopped the automation. Of the rebase stops on this fork:

RebaseStopped onCaused by
2026-09-23conflicts in the device recipe and the .github/workflows deletionone patch, one deletion of upstream files
2026-11-02a stale commit checked by the scheduled run, and a context-only .gitignore change read as a changed fork patch (both tooling bugs, fixed since); then, by hand, a real conflicta tooling commit, then the kernel hunk: upstream moved its function to a new file

Each fork has a scheduled job that compares the fork branch with upstream and keeps one tracking issue: opened on drift, updated while drift lasts, closed on the first clean run. The script’s exit code is the contract (clean, drift, error), and an error run touches no issue, so a broken checker cannot close a real drift report.

The rbw and Fladder reports, in order of cost:

  1. how many upstream commits the fork is missing, and the newest ones;
  2. git cherry of the fork patches against upstream: a patch marked - is already upstream and drops out on the next rebase, and when every patch is - the fork can be retired;
  3. files the fork patches touch that upstream also changed since the merge-base;
  4. a rebase probe in a throwaway worktree, nothing pushed.

For OpenWrt the behind count is noise: drift #7 was 195 commits behind, 51 of them under the Realtek target. The report instead lists must-read commits - those touching the device’s own files, files the fork patches modify, or shared files where the change reaches the device’s block or the shared defaults - and reports other boards’ entries in shared files separately. Drift #7 had 15 must-read commits and 4 shared-file commits that only added other boards.

Only the OpenWrt fork rebases automatically. After the drift report it rebases the fork range onto upstream main and compares old and new ranges with git range-diff. The result counts as clean when every fork commit is patch-identical, or when a commit marked changed has the same zero-context patch id, meaning only the surrounding lines moved. Drift #7: 88 of 90 fork commits identical, and the two MAC-force commits changed context only, because upstream renamed the function they sit in.

A clean result is force-pushed to a candidate branch, sks8300-next, never to the deployed branch, and the image build is dispatched. A conflict or a genuinely changed patch pushes nothing and the issue says why. The push and the dispatch use a personal access token stored as a repository secret: in this setup, pushes and dispatches made with the job’s automatic token started no workflow.

A clean, green candidate has passed the mechanical checks only. Two reviews remain.

The first reads the must-read commits against what the device actually uses: which SerDes modes, ports, features. For drift #7 three reviewers worked in parallel (the PCS calibration code, the DSA and Ethernet drivers, everything outside the target), and one finding mattered: RX link monitoring and a link-down report during RX calibration became active on every SerDes the switch uses.

The second looks past the candidate’s base: git log <base>..origin/main -- <files the range changed>. Upstream does not stop at the drift run. On 2026-11-13, five days after drift #7’s base, upstream committed a change to the same calibration gate whose commit message reports a link up/down/up flap within 50 ms in 84 of 90 link bring-ups over 30 warm reboots on an RTL9303 board with three 10GBASE-R links, and none after the change3. The switch’s 10G trunk is 10GBASE-R on that code path, so the candidate was skipped and the next weekly cycle builds on a base that includes the fix.

When a candidate is deployed, a post-flash script tags the flashed commit (sks8300-flashed-<date>, one recovery point per image that has run on the switch), moves the fork branch to it, and replays the fork commits made since the candidate was built. The replay matches commits by git range-diff: a commit with no counterpart in the flashed range is cherry-picked.

Squashing the stack or moving operator material out of the tree rewrites the fork branch. Three things follow from the mechanics above.

  • Deploy tags cover deployed commits only. On 2026-11-15, 8 commits on the OpenWrt fork branch were reachable from no sks8300-flashed-* tag, so an archive tag on the current tip comes before the force-push.
  • A replay that matches by patch sees every squashed commit as new. Probed on 2026-11-15 against the waiting next-00146e33 candidate: all 4 squashed commits came out as missing, the ones whose content the candidate already had applied as empty, and the docs commit conflicted, so the post-flash script would have refused to move the branch. Rewrite right after a deploy or before the next drift run, then dispatch the drift job so the next candidate is built from the new history.
  • A squash does not change whether the auto-rebase succeeds. Against upstream 7b46f9593e on 2026-11-15, the 93-commit branch and a 4-commit squash of the same tree both rebased cleanly, each with only the kernel patch changing context. The gain is upkeep: fewer commits to compare, and a revision suffix of +4 instead of +93.
  • The rationale of a real patch lives in its commit message. Keep each patch its own commit and squash only tooling and docs churn.
UpstreamPatchesDeploySetup
tens of commits a month or fewerapplication patches, any numberinstall a binarydaily report-only drift job, rebase by hand (rbw, Fladder)
hundreds of commits a weeka few, in shared codeslow build, risky deployweekly drift with a relevance filter, auto-rebase to a candidate, review gate, deploy by hand (OpenWrt)
upstream merged every patch0-retire the fork: archive it and install upstream’s release
  1. Forgejo, “Forgejo Actions | Reference,” Forgejo Documentation. https://codeberg.org/forgejo/docs/src/branch/next/docs/user/actions/reference.md ↩

  2. Forgejo, “Forgejo Actions | User guide,” Forgejo Documentation. https://codeberg.org/forgejo/docs/src/branch/next/docs/user/actions/overview.md ↩

  3. OpenWrt, “realtek: pcs: rtl93xx: report no link while waiting for RX calibration,” openwrt/openwrt commit e2ed57b957. https://github.com/openwrt/openwrt/commit/e2ed57b957 ↩