internals

A review log is a few lines appended by post-receive:

CI. forge attest checks each commit out into a worktree (one per repo, reused so build caches stay warm), runs .forge/ci in it (inside nix develop when there is a flake.nix and Nix is installed), signs the statement with ssh-keygen -Y sign -n forge-ci and appends it to refs/notes/ci, keyed by commit. pre-receive verifies against the server's own allowed_signers when forge.requireci asks it to; anyone who can push may add notes, as long as refs/notes/ci only fast-forwards.

Reviews. A review's parent is the nearest other review whose tip lies inside its branch; its layer is the commits between that parent (or main) and its tip. Status and revisions come from the review log and the refs, so nothing else is stored.

Sites. A deploy is a commit on refs/sites/<name> whose tree is the built output, so git provides content-addressed storage, dedup across deploys, history and revert by pushing an older deploy. Trailers record the source commit, the build command and who built it, and the commit carries an SSH signature when your key can sign. A preview is the same on refs/site-previews/<name>/<branch>. The build gets FORGE_SITE_BASE, the path it will be served from (/ on its own hostname).

The www/hosts/ directory of symlinks is the whole hostname registry. Without a pages domain, sites are plain files under /sites/<owner>/<repo>/<name>/ on the forge itself, and old /sites/... paths redirect to the hostname when there is one. Only the owner and collaborators deploy sites; anyone may deploy previews of their own branches.

Releases. forge release publish commits a tag's files to refs/releases/<tag> with a SHA256SUMS signed with ssh-keygen -n forge-release over the repo and tag too. pre-receive checks every sum, the signature (an owner's or collaborator's key), the tag and a size cap, and with forge.releaserequireci a verified pass for the tag's tree. post-receive extracts the tree into the store and hard-links the files into /<owner>/<repo>/releases/download/<tag>/, plus latest/; hard links, so the mirror copies them. Clones and fetches never see refs/releases. A private repo's go to the private root next to its pages, never the mirror.

Previews go when their branch does: post-receive deletes the preview ref, the served link and the hostname of a deleted branch. Previews of merged branches stay until the branch is deleted.

The store keeps every tree that was ever deployed until forge gc, which removes

• previews of review branches that are gone (deleted outside the hook, or before it cleaned up),
• hostnames whose deploy is gone,
• store trees that no www/sites or www/previews link points at.

A deploy extracts its tree before it links it, and touches a tree it reuses, so gc skips store entries changed in the last 10 minutes (--age) and is safe to run while people push. --dry-run shows what would go. Run it daily, from the host's crontab for the container (docker exec forge forge-admin gc) or the git user's on a VPS.

Repos are maintained by the same forge gc, in repack_repo: git repack -d --geometric=2 --write-midx --write-bitmap-index merges packs only until each is at least twice the next one's size, so a day's run rewrites the day's pushes and loose objects, not the repo, and one multi-pack index with a bitmap serves clones and fetches across the packs. It deletes only packs it rewrote and prunes nothing, so pushes can land while it runs. Then the commit-graph is rewritten as one layer (--split=replace, reusing the Bloom filters it has, adding any that old layers lack) and refs are packed, since every revision pins a loose refs/forge/keep/<sha>. Between runs, each build adds a commit-graph layer for its push.

Repo settings come from repo_setup, when a repo is created (repo new, ssh new, a push to a missing repo, an import) and for every repo on forge server init, which the container runs on boot: the hooks, receive.advertisePushOptions, transfer.hideRefs refs/forge so clones, fetches and pushes never see the pinned revisions (the build reads them directly; pre-receive also refuses them), and commitGraph.changedPathsVersion 2, filters that hash non-ASCII paths the same on every platform.

Backups: forge backup stages a copy of /srv/git without what a restore rebuilds (pages, extracted sites, caches, generated keys files, hooks, logs), uploads it with restic, prunes old snapshots, runs restic check and restores the new snapshot into a scratch directory to git fsck every repo and compare its refs. The copy is consistent mid-push: per repo it copies review logs and comments, then reads the refs, then hard-links the objects, which git writes before anything names them. It refuses a forge with no repos, or half the last backup's, so a new box can't push good snapshots out. forge-admin backups says how the last one went, and loudly when it failed or is a day and a half old.

Moving: forge restore latest on an empty forge unpacks a snapshot and rebuilds the rest: what server init and keys sync write, hooks, pinned revisions, site files, pages. The restored tailcat key keeps the tunnel address, so the edge follows the forge to a new box by itself. The README walks through a new slate and a VPS.

The offline copy: after builds, at most hourly, forge mirror syncs the forge's own pages, without sites, previews or the pages of single files and folders, to an R2 bucket. When slate doesn't answer, the edge's Caddy serves them from there with X-Forge-Offline: mirror, and a page the copy leaves out is a 404 that says so; sites, clones and pushes wait for slate.

Updates: deploy/slate/deploy.sh rsyncs the checkout to the box and rebuilds the container; the boot build refreshes every page. A change to lib/ or site/ changes the code hash in every fingerprint, so that first build renders everything.

Logs: .forge/build.log for builds, .forge/events.log for the events server, and backup.log and mirror.log, kept under a megabyte. events.jsonl is cut back to its last 1,000 lines once it passes a megabyte.

Conventions: shell stays POSIX (sh -n bin/forge); TypeScript uses erasable syntax only and imports name their .ts files, since Node strips types and runs the sources; no frameworks; comments say why. Pages must work without JavaScript, which only adds shortcuts, live updates and conveniences.

This guide is plain HTML and CSS with a few lines of script, and every link in it is relative, so it works on its own hostname and under any path. Edit guide/, run the checks and publish from main with forge site deploy guide.