One repo, universal build templates

Built from a live read of all five ISO repos, the shared gershwin-developer checkout.sh, the current release inventory, and GitHub's 2026 limits. Thesis: the five repos use five different build engines and only one of them (NextBSD) tests before publishing. Unify the build into two shared templates — container for Linux, vmactions for BSD — push everything identical into shared actions, and reduce each flavor to its overlay. The result is DRY, uniformly gated, and turns new variants into a fill-in-the-blanks exercise.

1Today: five repos, five build systems

The five ISO repos are not near-copies. They split into two substrate families, and within the Linux family they use three different engines. Only NextBSD tests before it publishes.

* freebsd only skips the build on PRs; it has no boot/screenshot verification.

• The drift is already visible: freebsd has no gate while nextbsd does; devuan's rolling tag is accumulating (4.97 GiB, two un-pruned dates) because uploadtool doesn't clean up; arch is at 1.91 GiB against a hard 2 GiB wall. Five copies of "roughly the same idea" diverge exactly like this.
• NextBSD is the reference for the good parts: its pipeline is changes → build → test → release, where test boots the ISO in QEMU+OVMF and asserts the desktop rendered (framebuffer unique-colour count > 1500, or OCR of the "System Disk" icon), with the gating step carrying no continue-on-error and release requiring needs.test.result == 'success'. That behaviour is what we spread to every target.

2The thesis: one build method per family, only overlays differ

Replace the three Linux engines with one container build, keep the two BSDs on one vmactions build, and reduce every flavor to the parts that genuinely can't be shared. Precisely:

• "Only overlays differ" is almost literally true — the honest version is "overlays + a ~3-function distro adapter differ." Everything else (assembly, live-boot, gate, publish, desktop install, naming) is one shared implementation.
• The one real engineering piece is dropping archiso/live-build: they secretly own the live-boot initramfs (find + mount the squashfs at boot). Removing them means owning that — see §4. This is where Arch's conversion cost concentrates; Debian/Devuan barely move.

3Shared layer 1 — composite actions every flavor calls

The parts that are identical no matter how the ISO was made are expressed as composite actions (bundles of steps dropped into any job with uses:). Each flavor writes its unique build inline and calls these for the rest. Fix a bug once → all flavors get it.

free-disk/action.yml            # reclaim ~25 GB on ubuntu-latest for a 2 GiB ISO
screenshot-gate/action.yml      # boot ISO in QEMU+OVMF → colour/OCR check → FAIL job if no desktop
publish-continuous/action.yml   # preserve tag: upload new ISO+screenshot → prune old ISO+screenshot (no sha256)

Two maximally-different flavors, Arch and NextBSD, end in the same three lines:

steps:                                   steps:
  - uses: actions/checkout@v4               - uses: actions/checkout@v4
  - uses: ./.github/actions/free-disk       - uses: ./.github/actions/free-disk
  - run: ./targets/archlinux/build.sh      - uses: vmactions/freebsd-vm@v1  (build.sh)
  - uses: ./.github/actions/screenshot-gate  - uses: ./.github/actions/screenshot-gate
  - uses: ./.github/actions/publish-continuous- uses: ./.github/actions/publish-continuous

• The build is the unique bit (red) — it stays inline. Disk-free, gate, publish are the shared bits — literally the same file reference in both. This is the whole value; it lives in the parts that don't differ, not the build.
• Uniform gate = "green means the same thing" on every ISO, and uniform publish kills the devuan-leak / freebsd-has-no-gate drift by construction.
• Trigger & build contract: a change to README.md alone never builds; any other change builds (paths-ignore: [README.md]). There is no "reuse the last ISO" fast path — the build always runs and the gate boots the ISO this run just built, so it can never test an image that doesn't exist. A push to main therefore goes build → gate → publish on its own; workflow_dispatch is only a manual re-trigger. (With several flavors sharing one repo, each caller scopes to targets/<flavor>/** + .github/** so a flavor rebuilds on its own target or shared-infra change — still never on README.)

4Shared layer 2a — each Linux flavor builds in its own distro container

Every Linux flavor builds its ISO inside a container of its own distribution, using that distro's native live-media tooling — not a reimplementation. The container is the per-flavor build environment; the only things shared across Linux flavors are the Gershwin install and the gate + publish tail.

• Native tooling, contained. Each distro's own live-media path is proven upstream; running it inside that distro's container means no cross-distro host workarounds — Devuan's debootstrap/keyring, Arch's pacman/mkarchiso only exist cleanly on their own distro. The container is the flavor delta.
• Only two things are shared across Linux flavors: the Gershwin install (git clone gershwin-developer → bootstrap.sh → checkout.sh → make install — identical everywhere, and the dominant build cost) and the gate + publish tail. Everything distro-specific stays in targets/<flavor>/.
• Stock images where possible. debian and archlinux use the official debian:latest / archlinux:latest images and install the ISO tool at runtime. Only Devuan needs a custom image, because Devuan's debootstrap (with the excalibur script) + keyring aren't on any stock image. The container never comes from another flavor's repo.
• Speed note: the container adds only the image pull/build (~seconds–minutes); it does not change build time. The wall-clock is dominated by the shared Gershwin source compile. If Linux builds need to be faster, cache or prebuild Gershwin — not swap the container.
• Superseded idea: an earlier draft proposed replacing every distro's live tooling with one hand-rolled busybox+overlayfs init. Rejected — it discards each distro's battle-tested live path for a bespoke one to maintain. Native tooling in a container is simpler and more robust.

5Shared layer 2b — the BSD template (vmactions)

FreeBSD and NextBSD already build the same way; the template just makes it explicit. Both assemble inside vmactions/freebsd-vm with the identical makefs → mkuzip → mkisoimages.sh toolchain (NextBSD is FreeBSD-derived). FreeBSD gains the screenshot gate for free the moment it calls the template.

• Only two things differ, both passed as parameters / owned by the target dir: the package base (FreeBSD base+ports vs the NextBSD-everything pkg) and the overlay (rc.d vs launchd). The template applies targets/<target>/overlays/, so freebsd gets rc.d and nextbsd gets launchd — neither carries the other's, no cross-contamination.
• Future non-FreeBSD BSDs are a bigger lift. OpenBSD/NetBSD can't build in the FreeBSD VM — they'd need a sibling template on vmactions/openbsd-vm / netbsd-vm with that OS's ISO tools. Supported in principle, but not "free" like a new Linux flavor. Document it as such.

6The only real per-flavor difference: overlays fork by init system

"Start LoginWindow / dshelper / gdomap at login" is the same intent everywhere but a different expression per init system. That's why overlays can't be unified — and it's fine, because overlays were never the thing to share.

Each target carries only its own init's overlay under targets/<flavor>/overlays/. Build-method uniformity buys a shared build workflow; it buys nothing on the init wiring, by design.

• XLibre shrinks the overlay further. Because every flavor runs the same XLibre server, the X configuration (xorg.conf.d snippets, the server wrapper, input/video driver setup) is no longer per-flavor — it moves into the shared gershwin-developer install (§7). What's left in each overlay is essentially just the init-system service wiring above, plus any boot/live-media plumbing the distro needs.

7What gershwin-developer owns (already shared)

• The desktop is an install, not an overlay. Every flavor already runs gershwin-developer's checkout.sh + make install to build the frameworks/apps/LoginWindow into /System. That's the big common asset and it's already one source of truth — no duplication.
• Push the thin cross-flavor tail there too: GNUstep defaults, the default wallpaper, the LoginWindow theme, the admin provisioning — install them from gershwin-developer so no flavor re-bakes them. Each flavor's overlay then shrinks to only its init wiring + X drivers + boot plumbing.
• Shared tests land here later: once the screenshot harness stabilizes across flavors, lift it into gershwin-developer/Library/Tests/ and have each template check it out the same way it already checks out gershwin-developer.

7a · One X server everywhere: XLibre, no Xorg

NextBSD already ships the XLibre server + input/video drivers. Standardizing all five flavors on XLibre — a drop-in X.Org fork — makes the display stack another shared layer: same server, same drivers, same config, on every flavor. XLibre publishes its own binary repos at packages.xlibre.net, so this is a repo-add, not a source build.

• The config is shared; the adapter just adds XLibre's repo. Because it's one server everywhere, the X config lives in gershwin-developer (§7). Getting the packages is a uniform "add the official XLibre repo + key, install, exclude Xorg" step: native port on FreeBSD/NextBSD (done); packages.xlibre.net for Arch and the Debian family.

# targets/archlinux/adapter.sh — confirmed layout from packages.xlibre.net/arch/
cat >> "$ROOTFS/etc/pacman.conf" <<'EOF'
[xlibre]
Server = https://packages.xlibre.net/arch/stable/$arch
EOF

# targets/debian/adapter.sh — confirm suite/component against packages.xlibre.net/debian/
install -m0644 xlibre-archive-keyring.gpg "$ROOTFS/etc/apt/keyrings/"
echo "deb [signed-by=/etc/apt/keyrings/xlibre-archive-keyring.gpg] \
  https://packages.xlibre.net/debian stable main" \
  > "$ROOTFS/etc/apt/sources.list.d/xlibre.list"

• Devuan reuses Debian's XLibre source. Because Devuan tracks the Debian stable base, the same packages.xlibre.net/debian stable apt line + key work unchanged — the Debian-family XLibre repo-add is written once and shared by both debian and devuan.
• The build now depends on an external repo. packages.xlibre.net availability and its signing key become build dependencies — pin/verify the key in the adapter, and consider mirroring the packages into the org (or a cache) if you want builds to survive that host being down. This is the real cost of "no Xorg," and it's isolated to the adapter.
• Check arm64 coverage. The Arch path is x86_64 only (Arch is x86_64-only anyway), but debian/devuan build arm64 too — verify packages.xlibre.net publishes arm64 debs before promising XLibre on those ISOs. If it doesn't, the arm64 builds can't get an X server on XLibre, which ties into the "publish arm ungated first" caveat (§14).
• "No more Xorg" is explicit: the shared package sets install xlibre-server + XLibre drivers and exclude/hold xorg-server/xserver-xorg-* so no flavor silently pulls Xorg back in as a dependency.

8Tags, names, titles & release presentation — one universal scheme

Today the five are inconsistent (mixed prefixes, arch tokens x86_64/amd64/aarch64/arm64, and timestamp formats). One template fixes all of it.

Tags — one rolling tag per flavor

Dual-arch ISOs share the flavor's tag as separate assets, keeping the tag count at five and grouping a flavor's arches together.

• Use archlinux, not arch, as the flavor token — "arch" collides with the CPU-architecture token (x86_64/aarch64). continuous-archlinux is unambiguous.
• Release title is just the flavor's display name: NextBSD, Devuan, Debian, FreeBSD, Arch Linux — proper-cased, distinct from the lowercase filename/tag token. Kept short deliberately: GitHub ellipsis-truncates release names in its narrow "Releases" sidebar and tag dropdown, and a one-word distro name never clips. "Continuous" is already conveyed by the tag (continuous-<flavor>), so it isn't repeated in the title. Each caller passes the name via publish-continuous's title: input.

ISO / asset names — one template

gershwin-on-<flavor>-<YYYYMMDDhhmmss>-<arch>.<ext>

flavor  = debian | devuan | archlinux | freebsd | nextbsd
stamp   = UTC, 14 digits, NO separators (sortable, cache-busting)
arch    = x86_64 | aarch64  (release token, normalized for EVERY OS — decoupled
                            from the build's internal triple: FreeBSD amd64 →
                            x86_64, dpkg arm64 → aarch64. NEVER amd64/arm64 here)
ext     = iso | img.zip     (img.zip = the RPi / raw disk-image variant)

gershwin-on-nextbsd-20260719101500-x86_64.iso
gershwin-on-debian-20260719101500-aarch64.iso
gershwin-on-debian-20260719101500-aarch64.img.zip

Screenshots publish in the tag, not the README

• Stop committing docs/desktop.png to git. The README holds one image and five flavors would churn binaries into history on every build. Instead, publish-continuous attaches the gate's screenshot to the release named to match the ISO — same stem, .png extension: gershwin-on-<flavor>-<stamp>-<arch>.png — and embeds it inline in the release body. It rotates with the ISO (new one uploaded first, old one pruned after) and adds zero git churn.
• The screenshot URL changes every build, exactly like the ISO's — the two always share a stem, so nothing in the release has a fixed "latest" URL. A README gallery therefore links to each tag page (…/releases/tag/continuous-<flavor>), which always shows the current shot inline in the body, rather than hotlinking a fixed asset URL.

Each continuous-<flavor> release contains

• No .sha256 sidecars. GitHub shows each release asset's SHA-256 digest natively, so the extra files are dropped — one ISO, one screenshot, nothing else.
• Every continuous release is a --prerelease — the project is early-stage, so no flavor's rolling build carries GitHub's "Latest" badge. This is a deliberate quality signal; keep it uniform across all flavors.
• Tag preserved, ISO + screenshot rotated in place. publish-continuous uploads the new (timestamped) ISO and its matching-named screenshot first, then deletes the previous build's ISO and screenshot — the release always holds exactly one current image and is never left empty. The git tag is created once and never re-cut (no --cleanup-tag).
• Trade-off to know: both filenames are timestamped (cache-busting), so their download URLs change each build — there's no fixed "latest" link for either. Point users at the tag page (…/releases/tag/continuous-debian), which always lists the current asset and shows the screenshot inline.

What a published release looks like

publish-continuous renders each continuous-<flavor> tag as one self-describing release: a proper-cased title, a body that leads with the desktop screenshot inline and nothing else but a build-log link, and exactly two assets whose stems match. Title, body and assets are regenerated on every publish, so the release never shows a stale or half-updated state. For nextbsd it renders as:

# ── title (releases list + tag page) ─────────────────────────────
NextBSD      Pre-release · tag: continuous-nextbsd

# ── body (Markdown) ──────────────────────────────────────────────
┌───────────────────────────────────────────────┐
│                                               │
│      [ About This Computer + desktop ]        │   inline image, embedded from
│                                               │   the matching .png asset below
└───────────────────────────────────────────────┘
Build log: …/actions/runs/<run-id>

# ── assets — exactly two, matching stems; GitHub shows the digest ─
gershwin-on-nextbsd-20260721000706-x86_64.iso     sha256:…   1.66 GiB
gershwin-on-nextbsd-20260721000706-x86_64.png     sha256:…    248 KiB

• The body is just image + build log — no "ISO:" or "commit:" lines, because the ISO's full name is already carried by the screenshot's matching filename, and the run is one click away via the log link.
• The digest column is GitHub's own, so there are no .sha256 sidecars to attach or prune — the release is literally one ISO + one screenshot.
• Dual-arch flavors (debian, devuan) add a second …-aarch64.iso, published ungated; only the gated x86_64 boot produces a screenshot, so the inline body image always depicts the x86_64 build. See the asset table above.

9The future custom-branch job — checkout.sh first

gershwin-developer/Library/Scripts/checkout.sh clones the 17 Gershwin/GNUstep source repos, but only on their default branch — its sole ref control is PINNED=1 (hardcoded SHAs) and SKIP_REPOS. No branch support.

    else
        git clone "$REPO"          # ← no -b, always default branch
    fi

• ~15-line change (prerequisite): add a per-repo REPO_BRANCH_<name> override mirroring the existing checkout_commit idiom, cloning with git clone ${BR:+-b "$BR"} "$REPO". Then a second job / a build-all input sets the branch and publishes to a separate branch-<name>-<flavor> tag so branch builds never clobber continuous-*.
• Land this in gershwin-developer before wiring the branch job — it's the one true prerequisite, self-contained, and harmless to the existing builds (they pass env through unchanged).

10Adding a new variant — the contributor guide

Adding a flavor is one per-flavor continuous-<flavor>.yml that builds the ISO in the flavor's own distro container and then calls the shared gate + publish, plus one targets/<flavor>/ dir holding that distro's native build. No forking a repo, no reimplementing live-boot.

on:
  push: { branches: [main], paths: ['targets/ubuntu/**', '.github/actions/**', '.github/workflows/continuous-ubuntu.yml'] }
  workflow_dispatch:
jobs:
  build:                                       # in the flavor's OWN distro container
    runs-on: ubuntu-latest
    container: { image: ubuntu:latest, options: --privileged }
    steps: [ install live tooling, checkout, build ISO → out/, upload-artifact ]
  test:    { uses: ./.github/actions/screenshot-gate,   with: { flavor: ubuntu } }
  publish: { uses: ./.github/actions/publish-continuous, with: { tag: continuous-ubuntu, title: Ubuntu } }

Trigger scoped to targets/ubuntu/** + shared .github/actions/** + the flavor's own workflow file — rebuilds on its own target or a shared-infra change, never on another flavor's edit or a README. Filenames use x86_64/aarch64; the distro's build maps them to whatever its bootstrap needs (dpkg arm64, etc.).

<native build>    # build.sh (debootstrap) | config/ (live-build) | profiledef.sh (mkarchiso)
ci/containers/    # ONLY if the distro needs a custom image (as Devuan does)
packages…         # the distro package set (incl. XLibre, never Xorg)

The contract a variant must honor

Checklist

• 1. Pick the family — any Linux you can bootstrap in a container → reusable-iso-linux; needs FreeBSD tools → reusable-iso-bsd.
• 2. Copy targets/_template-<family>/ → targets/<flavor>/; fill adapter.sh, package list, overlay.
• 3. Copy the caller → continuous-<flavor>.yml; set flavor / arches / tag.
• 4. Add <flavor> to the build-all matrix and a README gallery cell.
• 5. First run: tune the gate markers → once green, it auto-publishes continuous-<flavor> with the ISO + inline screenshot (no sha256).

• Free for the author: the screenshot gate, rolling-tag publish with delete+recreate hygiene, sha256, screenshot-as-asset, README gallery entry, universal naming — all inherited from the template.

11GitHub limits that actually bite

All re-verified against current GitHub docs. Only three constrain this — none is caused by consolidating.

Storage answer, directly: with delete+recreate each continuous-<flavor> holds ~1 ISO ≈ 1.5–2 GiB → the whole live set is ~10–15 GiB, none of it counting against any quota, no total cap. Five tags, or fifty, is fine.

12Migration: issues, history, cut-over

Moving into one home has two migration pieces. Issues are easy (native support); release history is the awkward one.

• Tickets transfer natively. gh issue transfer <n> gershwin-desktop/gershwin-desktop preserves body/comments/history and leaves an automatic redirect, so archiving the old repos won't break links. Loop it over each repo's open issues.
• Recreate labels first. A transferred issue keeps a label only if a same-named label already exists in the destination; milestones/project placement are lost. Recreate the shared label set (consider per-flavor prefixes: debian:, freebsd:…), and note PRs can't be transferred — drain/close open ones before archiving.
• Release history won't merge. You can't transfer-merge five repos (only one can hold the name). The Debian 202601 tag alone is 33.5 GiB / 70% of all release storage. Recommended: leave historical tags in the old repos, archive them read-only, link from the new README. Re-uploading assets is hours of transfer for no real gain — continuous builds don't need the history.

13Rollout: fork → POC → PR → replace

• 0 · Prereq — add per-repo branch override to gershwin-developer/checkout.sh (~15 lines). Unblocks the future custom-branch job; harmless now.
• 1 · Fork & scaffold — fork gershwin-desktop/gershwin-desktop; add the two composite actions, the two family templates, and targets/ + tests/screenshot/.
• 2 · POC on the cheapest pair — prove the shared path on debian + devuan (Linux template) or freebsd + nextbsd (BSD template). Least new work, validates the template + gate + publish end-to-end.
• 3 · Stress-test with Arch — convert Arch off mkarchiso onto the container template + shared live-init. This is the real engineering; if it works, the template is proven universal.
• 4 · build-all — wire the workflow_dispatch matrix fan-out; run every flavor in parallel once, green.
• 5 · PR & review — open the PR against gershwin-desktop/gershwin-desktop; compare ISOs + screenshots against the current per-repo outputs.
• 6 · Replace — transfer open issues (§12), archive the five old repos read-only, point their READMEs at the monorepo.
• 7 · Later — add the custom-branch job (uses step 0); migrate tests/screenshot/ into gershwin-developer/Library/Tests/ as the shared suite.

14Risks & gotchas, consolidated

• Arch's live-boot conversion is the one genuine chunk of work — dropping mkarchiso means owning the live initramfs. Mitigated by the shared busybox+overlayfs init; still the riskiest step.
• 2 GiB asset cap — Arch at 1.91 GiB. Independent of layout; keep compression tight.
• Screenshot thresholds are NextBSD-tuned — each flavor validates its colour floor + OCR marker once. Arm boot-tests are unsolved; publish arm ISOs ungated at first, clearly labelled.
• Single-repo blast radius — a bad push to a template or shared action can break all flavors. Mitigate with tight paths:, fail-fast: false on matrices, and branch protection.
• Non-FreeBSD BSDs aren't free — OpenBSD/NetBSD need their own VM template.
• Concurrency, storage, minutes are all non-issues — org-wide 20-job budget already shared, release assets unquota'd, public-repo minutes free.

15Alternative if you want to de-risk

Hub-repo first. If the full monorepo feels big, ship an intermediate: make gershwin-desktop/gershwin-desktop an orchestrator that retrofits the screenshot gate into each existing repo and hosts a release-index / gallery, keeping the five repos in place. It buys uniform gating this week with no migration, and its hub becomes the monorepo's build-all later. The downside is the five build engines still diverge — you don't get "everything builds the same way" until you do the real consolidation. Recommended only as a stepping stone, not the destination.