{"canonical_url":"https://engineer.company/glossary/forge/","content_markdown":"# Forge\n\n## What it is\n\nA forge, also called a software forge, a code forge or a git forge, is the\nserver a team agrees to treat as the home of its repositories, together with the\nservices it runs around them. Every full clone of a Git repository carries the\nwhole history, so in principle no copy outranks another. In practice a team\nneeds one place to push to, one place that decides who may read and write, and\none place where the conversation about the code happens. That place is the\nforge.\n\nUnderneath, a forge keeps bare repositories, the history-only form with no files\nchecked out, and speaks one or more of Git’s transfer protocols. The Git book\nlists four: the local protocol for a directory on the same machine, HTTP, SSH,\nand Git’s own protocol, a daemon on port 9418 with no authentication at all.\nEverything else is built on top, and how much varies widely.\n\nForgejo’s documentation describes the full end of the range: issue tracking,\npull requests, an integrated wiki, a package registry for many language\necosystems, Forgejo Actions for running jobs, repository mirrors, migration from\nother services, branch and tag protection, and webhooks. Soft Serve sits at the\nother end. It describes itself as a “self-hostable Git server for the command\nline”: a single binary called `soft` that serves repositories over SSH, HTTP or\nthe Git protocol, controls access with SSH public keys, and supports\ncollaborators, private repositories and webhooks. Both are forges; they differ\nin how much of the team’s work they try to hold.\n\nForges have also started to talk to each other. ForgeFed, a protocol that\nfederates platforms for hosting and collaborating on software projects, built as\nan extension of ActivityPub, models repositories, ticket trackers, patch\ntrackers, projects and teams as actors that send each other activities. Its aim\nis a common language across networks of forges and project management tools, so\nthat a person on one server can open a ticket against a repository on another,\nand a repository can move between servers while the old copy is archived as\nread-only and points to its new home.\n\n## Why it matters\n\nThe forge is where policy becomes enforceable. A rule that lives on a\ndeveloper’s machine applies only while that machine is set up correctly, but a\nhook on the server runs on every push. Git’s `pre-receive` hook reads each\npushed ref as an old id, a new id and a name on standard input, and if it exits\nwith a non-zero status, none of the refs are updated. Branch protection,\nrequired reviews and signed-commit checks on larger forges refine the same idea:\nthe shared copy refuses what the team has agreed not to accept.\n\nChoosing a forge is also choosing who holds the code. A hosted service takes on\nthe running costs and the uptime, and in return the code, the access list and\nevery discussion sit on someone else’s hardware under someone else’s terms.\nSelf-hosting reverses the trade. Neither choice is free, and the difference\nmatters most to a business that tells its clients where their data lives.\n\nA forge also holds data that Git does not. Commits and tags travel with every\nclone, while issues, review threads, access lists and server-side hooks belong\nto the forge alone. That split decides what a backup has to cover and what a\nmove between forges has to carry.\n\n## What it looks like in practice\n\nThis company runs its own forge, and three projects on this site show what that\ntook.\n\nThe company’s source code used to live on a third-party hosting service, and the\nproject to\n[deploy the company’s own git forge](/portfolio/your-code-on-your-own-hardware/)\nstarts from the observation that running a forge means running a forge:\nauthentication, access control, storage, backups, and a public face for it. The\nforge is Soft Serve, a single binary supervised by the operating system, chosen\nfor being SSH-first with no administrative web interface. It is private by\ndefault: anonymous access is refused, keyless access is refused, and every\ndeclared repository is marked private. Its SSH listener binds only to the\nloopback interface on port 23231 and is reached from outside through a jump\nhost. A multiplexer that would put HTTPS and git over SSH on one public port is\nwritten and left switched off, because a listener nobody uses is surface. The\nresult is stated plainly: the company hosts its own code on its own hardware.\n\nThis site’s own repository lives there: its instructions name the self-hosted\nforge, Soft Serve over SSH, as the canonical remote, call the older hosted copy\na legacy mirror, and say there is no hosted CI: the quality gate runs locally\nand in git hooks.\n\nA server-side hook needs to be tested in the receiving environment of a real\nGit push, so the hook was\n[rehearsed against a real bare repository and a real push](/portfolio/rehearsed-the-forge-ci-hook-found-2-defects/)\nbefore being trusted. The rehearsal creates a bare repository, installs the\nhook, clones, commits, pushes and asserts on both the accept and the reject\npath. It found two defects, neither visible in the file. The second is the\ninstructive one: Git exports a variable naming the repository directory when it\nruns a hook, the test suite the hook started inherited it, and nineteen tests\nwent red on correct code until the environment was cleared at the boundary. The\npage also names its limit: forced updates and branch deletions are pushes the\nrehearsal does not construct.\n\nAll of this shares\n[one single-core host with 512 MB of memory](/portfolio/a-whole-company-on-one-small-server/)\nand everything else the company serves in public, from the seven TLS domains\nto the onion service, a Gemini and a Gopher server and intrusion banning.\nBackup automation is implemented separately; that is distinct from active\nbackups. A forge with a web panel would have been one more resident application\non that budget, which is why web-panel platforms were ruled out at the design\nstage; on that host, available memory bottomed out at about 310 MB of 464 over\na recorded day of samples.\n\n## Where it goes wrong\n\nAnonymous visitors get read access by default on some forges. Soft Serve’s\ndocumentation says that out of the box it gives read-only permission to\nanonymous connections, governed by two settings, `anon-access` and\n`allow-keyless`. A private forge sets the first to `no-access` and the second to\nfalse, and the result is worth testing from a machine with no key loaded. Git’s\nown daemon is blunter still: the Git book notes that a repository it serves is\neither available to everyone to clone or not served at all.\n\nA hook that calls Git in another directory acts on the wrong repository. During\na push, Git runs the receiving hooks inside the bare repository and exports\n`GIT_DIR` and related variables so that Git commands in the hook find it.\nAnything the hook starts inherits them, including a test run in a checkout\nsomewhere else. The githooks manual says to clear these variables before working\nin a foreign repository. A minimal `pre-receive` hook that tests each pushed\ncommit in a throwaway directory does it in a subshell:\n\n```sh\nwhile read -r _ newrev _; do\n  git cat-file -e \"$newrev^{commit}\" 2\u003e/dev/null || continue\n  tree=$(mktemp -d)\n  git archive \"$newrev\" | tar -x -C \"$tree\"\n  (\n    unset $(git rev-parse --local-env-vars)\n    cd \"$tree\" \u0026\u0026 ./run-tests\n  ) || exit 1\ndone\n```\n\nA restored forge comes back with its code and without its rules. Any clone can\nrepopulate a lost server’s repositories, but the Git book warns that server-side\nhooks and similar settings stay behind, and issues, reviews, keys and access\nlists were never in the clones. Backing up a forge means backing up its data\ndirectory and its configuration, then restoring both somewhere and checking that\na push the hook should reject is rejected.\n\nEvery listener a forge opens is something to defend. Soft Serve’s sample\nconfiguration has SSH on port 23231, HTTP on 23232, the Git daemon on 9418 and a\nstatistics server on 23233. A team that only pushes over SSH can switch the rest\noff or bind them to loopback, so the open ports stay the size of what is used.\n\nMoving to another forge carries the code and strands the conversation. A mirror\npush copies every ref under `refs/`, branches and tags included, and that is all\nit copies. Issues, review threads, labels and access lists need the new forge’s\nmigration tool, or a protocol such as ForgeFed’s, which copies commits, tags,\ntickets, merge requests and comments and leaves the old repository archived and\npointing at the new one.\n\n## Further reading\n\n- [ForgeFed specification](https://forgefed.org/spec/) — the federation protocol\n  for forges, with its actors, its activities and the move flow that archives an\n  old repository.\n- [Soft Serve](https://github.com/charmbracelet/soft-serve) — the project’s own\n  documentation for a single-binary, SSH-first Git server, including the\n  `anon-access` and `allow-keyless` settings.\n- [Forgejo documentation](https://forgejo.org/docs/latest/) — administrator and\n  user guides for a full-featured self-hosted forge, from installation and\n  backups to Actions and mirrors.\n- [githooks](https://git-scm.com/docs/githooks) — every hook Git runs, including\n  `pre-receive` and the environment a push hook inherits.\n- [The Protocols](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols)\n  — the four ways Git moves data between machines and what each costs in setup\n  and security.\n- [ActivityPub](https://www.w3.org/TR/activitypub/) — the W3C recommendation\n  that ForgeFed extends.\n\n\u003chttps://engineer.company/glossary/forge/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"What a forge adds on top of the repositories it serves, how small one can be, and where self-hosting the shared copy of your code tends to bite.","formats":{"gemtext":"https://engineer.company/glossary/forge/index.gmi","gopher":"https://engineer.company/glossary/forge/gophermap","html":"https://engineer.company/glossary/forge/","json":"https://engineer.company/glossary/forge/index.json","markdown":"https://engineer.company/glossary/forge/index.md","pdf":"https://engineer.company/glossary/forge/index.pdf"},"kind":"page","language":"en","title":"What is a forge?","url":"https://engineer.company/glossary/forge/","version":1}