@foss.global/forgefixtures

Disposable, digest-pinned forge instances for integration tests. @foss.global/forgefixtures starts a real Gitea or GitLab Community Edition from its pinned upstream image behind a verified loopback TLS endpoint, bootstraps an administrator token through the forge's supported tooling, seeds realistic data through the documented REST APIs, and returns a ground-truth manifest read back from the forge itself. Every Docker resource carries ownership labels, so resources left behind by a crashed test process are removed by the next run.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Runtime Requirements

  • Linux (ownership checks read /proc)
  • Node.js 24.18 or newer
  • a reachable Docker Engine; for Gitea the socket is taken from the dockerSocketPath option, otherwise DOCKER_HOST, otherwise /var/run/docker.sock
  • for GitLab, a rootless Docker Engine: the omnibus image runs as root, and @apiclient.xyz/docker permits a root container user only after the daemon proves rootless mode. GitlabFixture defaults to the current user's rootless socket ($XDG_RUNTIME_DIR/docker.sock, otherwise /run/user/<uid>/docker.sock); a rootful daemon is refused
  • network access to Docker Hub for the first pull of a pinned image

Installation

pnpm add --save-dev @foss.global/forgefixtures

Usage

import { GiteaFixture, createDefaultGiteaSeedSpec } from '@foss.global/forgefixtures';

const fixture = new GiteaFixture({ seed: createDefaultGiteaSeedSpec() });
try {
  const runtime = await fixture.start();
  // runtime.baseUrl           https://127.0.0.1:<port>
  // runtime.caCertificatePem  the only CA that issued the endpoint certificate
  // runtime.admin.token       administrator token with scope `all`
  // runtime.version           '28.2.0', verified against the image pin

  const manifest = fixture.seedManifest;
  console.log(fixture.seedReport); // { key, source: 'restored' | 'seeded', durationMs }
  const repository = manifest.repositories.find((repositoryArg) => repositoryArg.fullName === 'team-with-hyphens/public-repo');
  console.log(repository?.issues.map((issueArg) => issueArg.number)); // [1, 3, 4, 5, 6, 7]; #2 is a pull request

  const aliceToken = await fixture.createAccessToken({
    username: 'alice',
    tokenName: 'inventory',
    scopes: ['read:repository', 'read:user'],
  });
} finally {
  await fixture.stop();
}

start() returns only after Gitea answers /api/healthz, reports the pinned version through /api/v1/version, the administrator and its token exist, and, with the seed option, the seeded state is ready. The seed option is how a seeded fixture starts: its first start seeds the spec and stores a snapshot, later starts restore it (see Seeded starts and snapshots). new GiteaSeedBuilder(fixture).apply(spec) writes a spec into a running fixture instead, always fresh: use it for tests of the seed builder itself, and for a second layer only when it depends on something that happens at runtime; otherwise merge it into the one seed spec. A fixture is single-use: after stop() create a new instance. stop() may be called while start() is still running: the start is cancelled at its next checkpoint (an image pull is aborted), start() rejects with ForgeFixtureStoppedError, and stop() returns only after every resource that start created is removed. stop() is idempotent; if a removal fails, the remaining resources stay recorded, the failures are thrown together, and a later stop() retries them.

Seeded starts and snapshots

new GiteaFixture({ seed: spec }) keys the spec by the hex SHA-256 of the canonical JSON of the forgefixtures version, the Gitea image's repoDigest and the spec; any change to one of them is another key. The spec is validated inside start(), before the key, so an invalid spec fails the same way either way. Canonical JSON sorts object keys, leaves out undefined properties and encodes byte payloads (Uint8Array, Buffer) by their SHA-256; it throws on any value it cannot encode (non-finite numbers, bigints, Date, Map, other typed arrays, cycles), never stringifying one. There is no switch that turns the restore off; a test that needs a fresh seed uses apply.

  • Miss (seedReport.source 'seeded'): start() creates the administrator and its token, applies the spec through GiteaSeedBuilder.apply, waits until two state snapshots half a second apart agree, stops Gitea, archives its data directory and stores the snapshot, then starts Gitea again on the same data.
  • Hit ('restored'): before Gitea starts, a helper container mounts the snapshot's volume and, while that mount holds it, checks the volume's labels and the snapshot's digests and extracts the archive into the fixture's new data volume. A snapshot whose volume is gone by then is a miss. The administrator and its token come from the snapshot; no token row is added. seedManifest is the manifest the seeding run read back, with its per-run fields, baseUrl and every repository's htmlUrl and cloneUrl, pointed at this fixture; any other string naming the seeding run's address throws.

A snapshot lives in Docker, never on the host's filesystem and never as a live Gitea: a labelled volume holding data.tar, Gitea's whole data directory taken with Gitea stopped (configuration with the SECRET_KEY the encrypted columns were written under, the internal token and the JWT secrets, database, repositories, LFS, package and attachment stores, queues, indexers, the JWT signing key and the authorized_keys Gitea keeps for OpenSSH), and seed.json (administrator, manifest and the seed's kept secrets, see seedSecrets), plus a container named forgefixtures-gitea-seed-<key>, created and never started, whose labels carry both files' SHA-256. A restore checks both digests first; a mismatch throws an error naming the key and the snapshot's container and volume, and nothing is seeded instead. A start decides between restore and seed only once the restore helper's mount holds the snapshot's volume: Docker refuses to remove a volume a container uses, even forced, and every reaper skips one. A snapshot removed after the lookup and before that mount, typically by the reaper of another forgefixtures release, is a cache miss: the empty volume Docker created for the mount is removed again by its last holder (two starts that lost the same snapshot share it), the data volume is left as Docker created it, and the start seeds and publishes its own snapshot. The container's environment is fixed only after that decision, so a seed gets a new SECRET_KEY and a restore none (its app.ini holds the seeding run's); a restart keeps it. Only integrity failures fail a start: a digest mismatch, an unreadable or malformed record, or a volume of the snapshot's name carrying another snapshot's labels. Per-run values are applied again at every start: the host port, ROOT_URL, and the lifecycle's CA and certificate. Two processes that miss the same key at the same time both seed; Docker refuses a second container of the same name, so the first to create it publishes, and the other keeps its own seed for its run and removes its staged volume.

The opt-in test (test/test.gitea.restore.node.ts) seeds a run-unique default spec, restores it, and proves:

  • the restored state snapshot equals the seeded one except entries every start of the same data directory changes: conf/app.ini, in its ROOT_URL line only (the image's entrypoint writes the environment into it at every start); LevelDB's info log queues/common/LOG; and the Bleve store root indexers/issues.bleve/store/root.bolt, while the index segments stay equal. Modes and owners of every entry are equal too;
  • the restored administrator token works, a hit records no seed requests, and the restore time is logged;
  • the only stored value naming the seeding run's address is the push payload Gitea keeps per Actions run (action_run.event_payload, its compare_url among others). No REST route serves it (the test reads the runs and jobs routes) and a fixture has no runner that receives it, so it is left as stored. The mirror clones from http://localhost:3000, inside the container, so mirror-sync works after a restore, also into a secondOrigin fixture whose ROOT_URL names localhost where the seeding run's named 127.0.0.1 (probed 2026-11-15); webhooks keep their spec URLs; release asset and package URLs (the npm tarball included) are derived from ROOT_URL when served;
  • a tampered archive throws naming the key, and a process that loses the publish keeps its seed;
  • through a proxy on the Docker socket that acts at an exact point of a start: a snapshot removed between the lookup and the helper's mount makes the start seed and publish as a plain miss does (the data directory two levels deep equals the plain miss's), with no stray volume; a snapshot the helper holds survives another release's reaper, Docker answers even its forced removal with 409 volume is in use, and the restore completes;
  • a restart after a seed and after a restore keeps the SECRET_KEY (compared as digests).

Snapshots are a cache: any release's reaper evicts other releases' snapshots that no container holds, a start that loses its snapshot before holding it seeds instead, and only integrity failures fail a start. While lanes on one host run different forgefixtures releases, their starts therefore re-seed rather than restore. A snapshot is removed by the reaper once its labels name another forgefixtures release or Gitea image, and a staged volume nobody published, of any release, once its stager is stale; there is no age, size or count limit. docker container prune removes the snapshot containers too (the next start of the key seeds again and the reaper removes the orphaned volume). A spec that differs on every run (a random value in it) seeds every run and leaves one snapshot per run until the release changes.

GitLab

import { GitlabFixture, GitlabSeedBuilder, createDefaultGitlabSeedSpec } from '@foss.global/forgefixtures';

const fixture = new GitlabFixture(); // rootless daemon of the current user
try {
  const runtime = await fixture.start(); // several minutes: omnibus runs gitlab-ctl reconfigure on first boot
  // runtime.admin.username  'root'
  // runtime.admin.token     personal access token with scopes `api` and `sudo`
  // runtime.version         '19.4.1', verified against the image pin

  const manifest = await new GitlabSeedBuilder(fixture).apply(createDefaultGitlabSeedSpec());
  const app = manifest.projects.find((projectArg) => projectArg.pathWithNamespace === 'parent-group/sub-group/app');
  console.log(app?.issues.map((issueArg) => issueArg.iid)); // [1, 2, 3, 4]; merge requests count separately

  const token = await fixture.createAccessToken({ username: 'carol', tokenName: 'inventory', scopes: ['read_api'] });
} finally {
  await fixture.stop();
}

GitLab is configured through GITLAB_OMNIBUS_CONFIG with GitLab's memory-constrained settings (Puma in single mode, Sidekiq concurrency 10, Prometheus monitoring off) and external_url set to the fixture's HTTPS origin, with nginx listening on plain HTTP behind the TLS terminator and Let's Encrypt off. start() returns once all of these hold:

  • the image's post-reconfigure hook (GITLAB_POST_RECONFIGURE_SCRIPT, run by the image's /assets/init-container) has run, so gitlab-ctl reconfigure finished
  • Docker reports the container healthy through the image's own gitlab-healthcheck, gated on that hook
  • an unauthenticated /api/v4/version answers 401 through the proxy, so nginx, Workhorse and Puma serve the API
  • an administrator token exists and /api/v4/version reports the pinned version

Tokens are created with GitLab's documented programmatic method, gitlab-rails runner; the script is passed on stdin (runner -), so it never appears in process arguments. The default startup deadline is 12 minutes after the container starts; the image pull has its own deadline. Stop-during-start behaves exactly as for Gitea.

Talking to the fixture

The endpoint certificate is issued by a certificate authority that exists only in the memory of the lifecycle. Nothing changes process-global TLS state, so a client must trust runtime.caCertificatePem explicitly. fixture.http is such a scoped client: it trusts only that CA, refuses URLs outside the fixture origin before sending credentials, never follows redirects, and bounds time and response size.

const user = await fixture.http.requestJson({
  method: 'GET',
  url: '/api/v1/user',
  headers: { authorization: `token ${runtime.admin.token}` },
  expectedStatus: [200],
});

The endpoint is served by an in-process TLS-terminating reverse proxy that listens before the container starts. Each forge is therefore configured with its exact external origin (Gitea ROOT_URL, GitLab external_url), and the proxy forwards requests with the client's Host header and X-Forwarded-Proto: https, as a correctly configured production proxy does. Links the forge generates, including pagination Link headers (GitLab keyset pagination included), Git LFS action URLs and GitLab web_url values, use the fixture origin.

Recording requests

new GiteaFixture({ recordRequests: true }) makes the fixture's TLS proxy record every request it forwards to Gitea, so a test can prove that a client wrote nothing to the source forge. The proxy is the same one that serves runtime.baseUrl, and it is the only route to Gitea: clients use runtime.baseUrl and runtime.caCertificatePem exactly as without recording, and URLs Gitea generates (clone URLs, LFS actions, pagination links) cannot route around the log. Requests and responses pass through unaltered and streamed.

A record holds only the method, the path without its query, the service query parameter (as git-upload-pack, git-receive-pack or unrecognized), and the operation of Git LFS batch requests (POST .../info/lfs/objects/batch). The batch body is read alongside the forwarded stream for that one field (up to 1 MiB; a larger, encoded, malformed or unfinished body records unrecognized). Headers, credentials, other query parameters and bodies are never kept.

const fixture = new GiteaFixture({ seed: createDefaultGiteaSeedSpec(), recordRequests: true });
const runtime = await fixture.start();
const mark = fixture.requestLog.mark(); // the fixture's own startup requests, and its seed requests when it seeded, are recorded too

// … run the client under test against runtime.baseUrl, trusting runtime.caCertificatePem …

fixture.requestLog.assertReadOnly({
  since: mark,
  requiredKinds: ['upload-pack-advertisement', 'upload-pack', 'lfs-batch-download', 'lfs-object-get'],
});
console.log(fixture.requestLog.records(mark)); // frozen snapshot

With seed, a start that seeds records the seed requests and a start that restores does not, so take the mark() after start() (after apply when seeding that way). assertReadOnly() throws ForgeFixtureRequestLogError unless every record in the window is on the read-only allowlist and every required kind occurred. The allowlist is: any GET or HEAD without a service query parameter (a push starts with info/refs?service=git-receive-pack); GET <owner>/<repo>/info/refs?service=git-upload-pack and POST <owner>/<repo>/git-upload-pack; Git LFS batch POST with operation download; and Git LFS object GET. The error lists the offending records (error.offending, method, path, service and operation only) and the missing kinds (error.missingKinds). classifyForgeFixtureRequest() exposes the classification of one record. The log stays readable after stop(). Without recordRequests, fixture.requestLog throws.

On a secondOrigin fixture every record also carries localAddress, the address the request arrived on (127.0.0.1 or 127.0.0.2); other fixtures' records keep the shape above. Requests the edge filter refuses never reach Gitea and are not recorded.

SSH, a second origin and the freeze controls

These emulate the production paths and the Gitea freeze stack of a forge migration (the S11 freeze proof): OpenSSH with Gitea's forced gitea serv, two host names in front of one Gitea, the global Git hook, the HTTP filter and the restart that turns cron and mirrors off.

import { randomBytes } from 'node:crypto';
import { GiteaFixture, giteaFreezeCanarySeed } from '@foss.global/forgefixtures';

const nonce = randomBytes(16).toString('hex'); // the window's marker
const fixture = new GiteaFixture({ seed: giteaFreezeCanarySeed, ssh: true, secondOrigin: true, recordRequests: true });
const runtime = await fixture.start();
// runtime.baseUrl  https://localhost:<port>
fixture.origins;      // [{ baseUrl, connectAddress: '127.0.0.1' }, { baseUrl, connectAddress: '127.0.0.2' }]
fixture.sshEndpoint;  // { host: '127.0.0.1', port, user: 'git', hostPublicKey: 'ssh-ed25519 …' }
fixture.seedSecrets;  // { accessTokens: [{ username, name, token }], sshPrivateKeys: [{ username, title, privateKey }] }

await fixture.registerRunner('runner-1');                         // a global Actions runner, enabled, offline: { id, uuid, name }
await fixture.restartWithFreezeSettings(true);                    // cron and mirrors off, LFS over pure SSH off
await fixture.setFreezeHook(`code.foss.global is frozen (${nonce})`); // every push refused with this message
fixture.setEdgeFilter({ marker: nonce });                         // 503 and `X-Gitea-Freeze: <nonce>` to every write
// … and back: setEdgeFilter(null), setFreezeHook(null), restartWithFreezeSettings(false)
  • Configuration of every Gitea fixture. Gitea runs with START_SSH_SERVER=false, SSH_ROOT_PATH=/var/lib/gitea/ssh and LOCAL_ROOT_URL=http://gitea:3000/, and its container answers to the network alias gitea on the lifecycle's network (also when a restart re-creates it). Gitea therefore keeps authorized_keys for OpenSSH in its data directory instead of running its own SSH server, and every snapshot's authorized_keys matches its database. SSH_PORT is Gitea's default, so the ssh_url Gitea advertises does not name the fixture's port.
  • ssh (default off) starts a sidecar from the pinned non-rootless image of the same Gitea release (giteaFixtureSshImage; the rootless image has no sshd) after the seeded state is ready: sshd (OpenSSH 10.3p1 on Alpine) as uid 1000 with every capability dropped and no-new-privileges, Gitea's data volume mounted, a fresh Ed25519 host key generated at every start on a tmpfs (never in the data volume or a snapshot), only the user git by public key from Gitea's authorized_keys, whose forced command runs gitea serv. Its port 2222 is published on 127.0.0.1; start() returns once that port has sent an SSH-2.0- banner. Production runs OpenSSH as root with privilege separation; the forced-command path and the remote: messages are the same. sshEndpoint throws without the option or while the fixture is not running.
  • secondOrigin (default off) makes the TLS proxy listen on 127.0.0.1 and on 127.0.0.2 on the same port (on a port taken on 127.0.0.2 it picks another, at most three times, then throws naming both addresses), with one certificate (it names localhost), one filter state and one request log. runtime.baseUrl, Gitea's ROOT_URL and seedManifest name https://localhost:<port>; a client reaches the second origin by connecting to 127.0.0.2 for that host name (Git: http.curloptResolve=localhost:<port>:127.0.0.2). 127.0.0.2 binds on Linux without configuration (macOS needs a loopback alias). Without the option the base URL stays https://127.0.0.1:<port> with one listener. origins throws without the option or while the fixture is not running.
  • setFreezeHook(message | null) writes a pre-receive hook and its message to /var/lib/gitea/freeze-hooks in the data volume (never a tmpfs, so a restart keeps it) and points core.hooksPath in the git configuration Gitea's Git commands read (/var/lib/gitea/home/.gitconfig) at it, then reads both back. Every push, over HTTPS or SSH, is refused with pre-receive hook declined and the message as a remote: line; fetches go on. null unsets core.hooksPath and removes the directory.
  • setEdgeFilter({ marker? } | null) applies the freeze runbook's HTTP allowlist in the TLS proxy, on both origins: GET and HEAD pass except the push discovery (info/refs?service=git-receive-pack), archive generation (…/archive/<name>) and the GET routes that write (/user/activate, /user/oauth2/, /login/oauth/authorize, /user/logout); POST passes only for git-upload-pack and the Git LFS batch endpoint; everything else (the LFS object PUT, the runner API, every API write) is answered 503 with Retry-After: 3600, the marker in X-Gitea-Freeze and in the body. Without a marker a refusal carries none, like a stale or foreign freeze configuration. forgeFixtureEdgeFilterRefusal(method, target) exposes the decision.
  • restartWithFreezeSettings(frozen): true saves Gitea's configuration beside it once and writes [cron] ENABLED=false, [mirror] ENABLED=false and [server] LFS_ALLOW_PURE_SSH=false into it through gitea config edit-ini, then restarts Gitea: /api/v1/admin/cron lists no scheduled task and update_mirrors is gone. false puts the saved configuration back and restarts, so Gitea's defaults apply again (writing ENABLED=true instead would schedule every task, because each inherits [cron] ENABLED). Both return once Gitea is healthy; the hook, the filter and the sidecar stay.
  • registerRunner(name) registers a global Actions runner as act_runner register does: a token from gitea actions generate-runner-token, then the runner API's Register call (Connect-Protocol-Version: 1). It returns { id, uuid, name } as /api/v1/admin/actions/runners lists it; the runner's credentials are dropped, it never polls (status offline, no job taken) and stays enabled until an administrator disables it.

giteaPullRequestArchiveSeed holds the pull request cases a pull request archive measures (S9 ruling D12), opt-in beside the default seed. See Pull request seed.

giteaFreezeCanarySeed is the freeze proof's canary alone, with the production canary's names and settings: the private organization freeze-canary with the private repository probe (README on main; units code, issues, pull requests, releases and packages only; the pull request unit is on, as production's must be, because a disabled unit hides the repository's pull requests and every pull plan then refuses instance-wide), and the restricted, private user freeze-canary-probe (no own repositories, no organization creation) with the kept Ed25519 key freeze-proof@gitzone_dev and the token freeze-proof (read:user, read:organization, write:repository, write:issue, write:package), who writes to probe through the granular team probe-writers (code, issues, releases and packages on write, no other unit: repo.pulls stays none) only. Its token and private key are in seedSecrets. The opt-in tests prove on Gitea 28.2.0 that the canary sees exactly its organization and repository, that every canary write (issue, release, generic package, LFS upload, OCI blob upload, archive, push discovery, HTTPS and SSH push) is accepted on both origins while Gitea is open, the restricted user's organization package writes included, and that the full stack refuses every one of them with the nonce.

Pull request seed

giteaPullRequestArchiveSeed is plain spec data for the cases a Gitea pull request archive must carry; the default seed stays as it is. The public organization pull-archive (organization label needs-review) holds the public repository proposals (repository label enhancement; ada collaborates with read, ben with write), which eve forks as eve/proposals. Every pull request ends closed or merged:

# Key Case
1 merged by ada, merged by ben with the merge style (branch kept); enhancement, an attachment and a conversation comment; reviews ben APPROVED and cleo COMMENT, each with an inline comment, dan REQUEST_CHANGES, eve APPROVED and dismissed, gus PENDING with an inline comment, and a review requested from finn
2 closed-branch-deleted by ben, closed unmerged, branch closed-topic deleted; needs-review, a conversation comment, locked
3 from-fork by eve from eve/proposals fork-topic; a COMMENT review by cleo, closed unmerged
import { GiteaFixture, giteaPullRequestArchiveSeed } from '@foss.global/forgefixtures';

const fixture = new GiteaFixture({ seed: giteaPullRequestArchiveSeed });
await fixture.start();
const proposals = fixture.seedManifest.repositories.find((repositoryArg) => repositoryArg.fullName === 'pull-archive/proposals')!;
const merged = proposals.pullRequests.find((pullArg) => pullArg.key === 'merged')!;
// ['APPROVED', 'COMMENT', 'REQUEST_CHANGES', 'APPROVED', 'PENDING', 'REQUEST_REVIEW']
console.log(merged.reviews.map((reviewArg) => reviewArg.state));
console.log(merged.reviews.filter((reviewArg) => reviewArg.state === 'PENDING').length); // 1
await fixture.stop();

Gitea 28.2.0 facts the opt-in test asserts:

  • a merged pull request reads state: 'closed' with merged: true, merged_by the user who merged and merge_commit_sha the base branch's new head
  • once its branch is deleted, a pull request's head.ref reads refs/pull/<number>/head, while head.label keeps the branch name and head.sha the last head commit; the branch answers 404
  • a pull request from a fork names the fork in head.repo and its branch's commit in head.sha
  • the review list shows a site administrator every review, other users' PENDING drafts and their inline comments included (services/convert/pull_review.go), and hides a draft from everyone but its author; a requested review is a review with state REQUEST_REVIEW; a dismissed review keeps its state with dismissed: true; Gitea dismisses only approvals and change requests of an open pull request and has no dismissal message field
  • requested_reviewers is not the list of requested users: it holds every user whose latest undismissed review is an approval, change request, comment or request (GetReviewsByIssueID), in map order, so the manifest sorts it; pending drafts and dismissed reviews do not count
  • a pull request's attachments are its issue's (/issues/{index} assets), its lock is is_locked, and organization labels reach it as they reach issues
  • the merge route answers 405 Please try again later while the mergeability check Gitea queues at creation runs, so the builder waits for mergeable

Proving what a client wrote: state snapshots

The request log shows which requests reached Gitea; a state snapshot shows what they changed. fixture.snapshotState() reads every row of Gitea's SQLite database (giteaDatabasePath) and every entry below its data directory (giteaStateRoot, /var/lib/gitea: repositories, LFS, package, attachment and avatar stores, queues, indexers, configuration, keys and temporary files), files by the digest of their content and directories as such. It leaves out only giteaStateExclusions, each with its reason: the database file, which it reads row by row instead, SQLite's rollback journal, and the log directory. diffGiteaStateSnapshots(before, after) lists every difference: tables added or removed, rows inserted or deleted (keyed by row id), values changed (with table, row id and column) and entries added, removed or changed, sorted by table, numeric row id, column and path.

diffGiteaStateSnapshots(before, after, { excludeReadStamps: true }) leaves out exactly giteaReadStampFields, each with its reason: the columns Gitea 28.2.0 writes when it only serves a read. access_token.updated_unix is a token's last use, stamped by every request the token authenticates (token or Bearer header, query or Basic credentials; services/auth/oauth2.go userFromToken, services/auth/basic.go VerifyAuthToken). public_key.updated_unix and deploy_key.updated_unix are an SSH key's and a deploy key's last use, stamped by gitea serv after every Git command the key authenticated, fetches included (cmd/serv.go, routers/private/key.go UpdatePublicKeyInRepo). Every other column of those rows, their insertion and deletion, and every other table are compared. Without the option (the default) the diff reports every difference, read stamps included, so a test can prove which credential a read used; snapshots record the stamps either way. The option takes no column list: the list is the package's, and grows only with the Gitea source that writes a column on a read. test/test.gitea.readstamps.node.ts proves it: reads with the administrator token, the canary token and an SSH and an HTTPS fetch move exactly the two tokens' stamps and the SSH key's stamp in the default diff and leave the excluding diff empty, and a push with the same key is still reported with the option on.

A snapshot never holds the forge's text or bytes, which include password and token hashes: integers and reals are their decimal strings, text and blobs are sha256: and the hex digest of their bytes, and SQL NULL is null. A changed counter or timestamp therefore shows by how much it moved, and a changed text column only that it changed; a test that needs to recognise a stored text compares digests (sha256: of the UTF-8 text). The database is copied out of the container and read with node:sqlite. Take snapshots while the fixture is idle: a ForgeFixtureStateError refuses a database with an open journal before the copy (database-journal-open) and a copy a write ran through (database-copy-torn: a journal appeared during the copy, or the header's change counter moved), and reports a failed or timed-out copy as database-copy-failed.

const before = await fixture.snapshotState();
// … run the client under test …
const changes = diffGiteaStateSnapshots(before, await fixture.snapshotState());
// [{ kind: 'value-changed', table: 'package_version', rowid: '12', column: 'download_count', before: '0', after: '1' }, …]

Seed specs and manifests

GiteaSeedBuilder.apply(spec), which the seed option runs when it seeds, validates the whole spec before the first request, then creates:

  • users (with random passwords, held in memory for the run and discarded afterwards), optionally site administrators, deactivated, restricted or prohibited from signing in, with their own repository limit (maxRepoCreation, -1 for Gitea's default) and organization creation (allowCreateOrganization), with generated SSH keys (a plain title is Ed25519; { title, algorithm } picks ed25519, rsa, ecdsa-p256, sk-ed25519 or sk-ecdsa-p256; private halves are discarded unless an Ed25519 key sets keepPrivateKey), and access tokens (accessTokens: a name and Gitea 28 scopes, never all, never read beside write of one category; the user must be active, allowed to sign in and not scheduled for deletion), created through the admin CLI once the account's flags are set; organizations with public, limited or private visibility, an optional display name, description and website, optional extra members of their Owners team, and organization labels and project boards (created with the organization, before any repository)
  • repositories owned by users or organizations, auto-initialised on main, or created as a fork or a pull mirror of an earlier repository (mirrors clone from the instance's own loopback listener, which the fixture allows with ALLOWED_HOST_LIST=loopback:*), plus collaborators with read, write or admin
  • files on main (Actions workflows are files under .gitea/workflows/), branches created by one commit each, labels with colour, description and the exclusive and archived flags, empty project boards, milestones with description, state and due date (dueOn, a calendar date sent as 23:59:59 UTC, the end of the day Gitea's web form stores) and tags
  • issues and pull requests in the given order, authored through the administrator's Sudo header; repository and organization labels (labels, organizationLabels), milestones, assignees, closing and due dates (dueDate) are applied by the administrator so they are not silently dropped for authors without write access; reactions on issues and comments, authored through Sudo. Issue and comment attachments are uploaded by their author; a comment's editedBody replaces its body in a later second than its creation, so the edit shows in updated_at; a title with leading or trailing spaces is set by an edit, because Gitea trims titles only when it creates an issue; issues carry a verbatim ref, boards of their repository and organization, tracked times added through the user's Sudo, dependencies on earlier issues and a pin; Gitea 28.2.0 has no REST write for a time estimate, so the builder signs in as the issue's author through the web form for it (passwords stay in memory for the run only) and signs out; locked issues are locked by the administrator after every other step
  • pull requests (kind: 'pullRequest') opened through the author's Sudo from a branch of the repository or, with headRepository, of a fork declared later (opened once the fork exists, so these come after every other item of their repository and keep their numbers in declaration order); Gitea 28 opens one from a branch of the base repository only for an author with access to it (a collaborator or member), and from a fork for the fork's writers. Then, in order: attachments uploaded by the author, conversation comments (as on issues), repository and organization labels, reviews through each reviewer's Sudo (state COMMENT by default, APPROVED, REQUEST_CHANGES or PENDING, a draft only its author and site administrators read; at most one approval or change request per reviewer, because Gitea dismisses the earlier one when it creates the next without inline comments; inline comments anchor to new-file lines of a file the head branch adds), the dismissal of reviews marked dismissed (approvals and change requests only), review requests (requestedReviewers, read back as REQUEST_REVIEW reviews), the close or, for state: 'merged', the merge with Gitea's merge style through mergedBy's Sudo (the administrator by default) once Gitea reads the pull request mergeable, the deletion of the head branch (deleteHeadBranch) and the lock (locked). Reviews, dismissals and requests come while the pull request is open: Gitea refuses approvals, change requests and dismissals on a closed one
  • releases, drafts and prereleases included, with uploaded assets given as text or bytes (Uint8Array); an asset's name travels in the name query parameter, so any name Gitea stores survives, and one release may hold the same name twice
  • Git LFS objects uploaded through the batch API and committed under a .gitattributes LFS filter, so the commit holds their pointers
  • wiki pages, inactive webhooks, deploy keys, Actions secrets (random values that never leave the builder) and variables; then the template flag. A deploy key is an SSH key (read-only or read-write, any algorithm above; deploy keys with the same sharedKey label on different repositories carry one generated public key) or a Gitea 28 deploy token (kind: 'token'), whose value appears only in the create response and is discarded
  • organization Owners members, then teams, either whole-repository (permission) or granular (unitsMap, never both; Gitea 28 refuses the combination), optionally including all repositories, allowed to create repositories, and with a visibility, with members and repositories, inactive organization webhooks and organization Actions secrets and variables, once every repository exists
  • branch protections (a plain rule name disables pushing; a rule object takes every field Gitea reads back: priority, push, force-push, merge, bypass and approvals allowlists of users and teams, deploy-key flags, status checks, required approvals, review blocking, stale approvals, admin merge override, signed commits, protected and unprotected file patterns) and tag protections allowing users and teams. They come after every commit, because a protected branch refuses the API commits, and after the teams, because allowlists name teams and their members
  • packages (packages, a TGiteaSeedPackage union on type), uploaded in order through Gitea's registries with the administrator's token, after the protections:
    • generic: versions of files given as text or bytes, uploaded by PUT; file names may hold spaces, # and %, as Gitea's file name rule allows
    • container: manifests pushed in order over the OCI distribution API, with a registry token from /v2/token, blobs by monolithic upload and each manifest under each of its tags, or by its digest when it has none. An image manifest (OCI or Docker schema 2 media types) has a JSON config for its platform and layers named by labels: the bytes follow from the label, so one label is one blob in every image and owner. An index (an OCI index or, with format: 'docker', a Docker manifest list) lists image manifests declared before it; attestationFor marks a child as another child's attestation manifest with BuildKit's annotations. A tag pushed again moves
    • npm: versions published like npm publish --tag (default latest), then distTags through the dist-tags API and deprecations like npm deprecate; scoped names travel unencoded (@scope/name)
    • swift: versions published to the Swift registry with a stored zip source archive holding <name>/Package.swift, and metadata with a description and repository URLs; Gitea stores the package as scope.name. A version's alternateManifests add Package@swift-<swiftVersion>.swift files, written as Gitea keys them (5.10, 5.10.1, never 5.10.0), each beside Package.swift (root) or in the nested package directory <name>/Tests/Fixtures/ (nested); a key appears once per version, and at most 63 alternates sit beside Package.swift, because Gitea keeps at most 64 manifests
    • cargo: versions published through the Cargo publish API with their dependencies and features, then yanked where yanked is set
    • linkRepository links a package of any type to a repository of its owner through /-/link/{repo}
  • a repository's units (enabledUnits: code, issues, pulls, releases, wiki, projects, packages, actions), switched once the rest of its seed has run: the units not listed are off. The list must hold code and every unit whose content the repository declares
  • archiving of repositories marked archived (their pull requests are read back just before, because Gitea 28 answers 404 to every pull request route of an archived repository), then deletion of the users listed in deleteUsers, last

The canary attributes are read back as they are set, and the builder throws on a mismatch: tokens by their names and scopes, listed with the user's password, and each kept value by authenticating as the user; units from the repository's has_* fields (external trackers and wikis stay off); a kept key's public half against the key Gitea stores; maxRepoCreation and allowCreateOrganization from Gitea's database rows, because Gitea 28's REST API writes both and reads neither. Kept credentials never enter the manifest, whose shape is unchanged: after apply() they are in the builder's secrets getter (IGiteaSeedSecrets, in spec order; it throws until an apply has finished), and a fixture's seed option keeps them in its snapshot and serves them as seedSecrets. The private keys are unencrypted OpenSSH openssh-key-v1 keys.

The returned IGiteaSeedManifest is read back from Gitea after all mutations, except the pull requests of archived repositories, which are read just before archiving: stable IDs, numbers, states, authors (after deletion), issue titles and bodies verbatim, lock, due date, ref, board IDs, time estimate, pin order, original author (null unless a migration wrote one), tracked times, dependencies, created, updated and closed times, label names and IDs, milestone and attachments, comment bodies, times and attachments, repository and organization labels with colour, description and the exclusive and archived flags, project boards of repositories, organizations and users, milestones with description and created, updated, closed and due times, branch commits, every tag the repository holds (published releases create their own tags) with its commit, pull requests with title and body verbatim, state, merge (merged, time, who and merge commit), head ref, label, repository and commit, base ref and commit, merge base, labels, lock, Gitea's requested_reviewers, times, attachments, conversation comments and every review the administrator lists (pending drafts and requests included) with state, body, commit, dismissed, stale and official flags, time and inline comments (path, commits, diff hunk, positions), reaction and review counts, release IDs with draft and prerelease flags, LFS object IDs, accounts (display name, visibility, administrator, active, restricted and prohibit-login flags, SSH keys with ID, title, fingerprint, algorithm and public key), organization profile fields, teams with their permission, units map (null for a whole-repository team), includes-all, create-repository and visibility flags, members with their user IDs and repositories, webhook IDs, deploy keys (ID, title, mode, ssh or token, the shared key row ID, fingerprint or token mask, and the public key of an SSH key; never a token), Actions secret and variable names (never values), workflow paths, collaborators with their effective permission, fork, mirror, template and archived flags.

Packages read back in the forge source inventory's shape: manifest.packages holds an IForgeSourcePackageInventory (@foss.global/interfaces 3.3) per package, sorted by owner, type and name: the owner's id, the linked repository's id or null, every version Gitea lists (id, version, created_at verbatim) and every distinct file content once with the files that hold it (version id, file id, name), read through the v1 package API. Index versions carry references, read from the index manifest by digest; npm packages carry the dist-tags Gitea serves and npm versions their deprecation message ('' when none), read from the dist-tags API and the package document; Cargo versions carry their yank from the sparse index. Swift versions carry manifests: the builder asks Gitea's manifest route ({version}/Package.swift?swift-version=<key>) for '' and for the key of every alternate the spec placed, the keys taken from the spec and never from the archive, and records exactly the keys that answer 200, with the size and SHA-256 of the bytes served, sorted by key; other types carry no manifests. The builder throws unless the read-back matches the spec: the versions (tags lowercased, digests of manifests pushed without a tag), each generic file's name, size and SHA-256, each version's manifest digest, each index's children, the dist-tags, deprecations, yanks and links, and for Swift that '' and every root alternate answer 200 with the bytes placed and every nested alternate answers 303 to the release's own Package.swift. containerManifests lists every manifest a version holds with the media type Gitea serves it as, its size and its tags, read with HEAD; replacedContainerManifests lists the manifests moved tags left behind that no version holds, each checked to answer 404. These reads use the same paths a migration reader uses, so they count downloads of index manifests while seeding; see the counter facts below.

Release assets and issue and comment attachments carry their ID, UUID, name, size and SHA-256 digest. The digest is computed from the bytes downloaded through /attachments/{uuid} with the administrator's token (a redirect is refused), and the builder throws unless every release, issue and comment holds exactly the uploaded attachments: the same IDs, names, sizes and digests. Gitea itself exposes no attachment digest. Times are Gitea's RFC 3339 strings, verbatim; label colours are six hex digits without the #, as Gitea's API serves them. The builder also throws unless an issue reads back with the title, body, comment bodies, label IDs, lock and due date day it wrote, and unless labels and milestones are exactly those it created.

Protections appear as names (branchProtections, tagProtections) and as full rules (branchProtectionRules with every field above, allowlists sorted, and tagProtectionRules with their user and team allowlists). Gitea answers 201 for a branch protection yet silently drops allowlisted users without write access (approvals: without read access), teams without access to the repository, every team of a personal repository, and force pushing while pushing is disabled. The builder therefore throws unless every declared field reads back as declared.

createDefaultGiteaSeedSpec() covers behaviours an inventory reader must handle. These are observed facts of Gitea 28.2.0, asserted by the opt-in test:

  • issues and pull requests share one number sequence per repository
  • a deleted author's issues and comments are reattributed to the ghost user with ID -1
  • issue cases, all new issues after team-with-hyphens/public-repo #1 to #3: in public-repo, #4 carries the organization label needs-triage, #5 a comment edited after its creation (its updated_at is later than its created_at), #6 the closed title ' Title with outer spaces ' and #7 the body Tracked as limited-org/limited-repo#1.; in limited-org/limited-repo, which the foss.global e2e never publishes, #2 an issue attachment notes.txt and a comment attachment build.log, #3 a lock and #4 the due date 2027-03-15T23:59:59Z in the milestone q1-2027, due 2027-03-31T23:59:59Z
  • a reference to another repository's issue is resolved when it is written: #7 was written before limited-repo existed, and that repository's #1 has no issue_ref event in its timeline
  • a lock and a due date are timeline events (lock, added_deadline); the comment list holds only comments
  • issue state cases in limited-org/limited-repo: #5 the ref refs/heads/main and the exclusive label area/backend (the repository also has the archived label legacy), #6 the boards Repository board (type repository) and Organization roadmap of limited-org (type organization), #7 a time estimate of 5400 seconds (a change_time_estimate event), #8 a 1800-second tracked time of alice, #9 a dependency on #5, #10 pinned (pin_order 1); every other issue keeps '', no boards, 0 and no entries, and no issue has an original author
  • project listings need the issue token scope beside the scope of the route's owner group: /orgs/{org}/projects needs read:organization, /users/{username}/projects (an organization's boards too) read:user, /repos/{owner}/{repo}/projects only read:issue; a site administrator passes the Projects unit check. Anonymous callers read a public user's boards and get 404 for a limited organization and its repositories
  • with time tracking or dependencies switched off for a repository, /issues/{index}/times answers 404 timetracker is disabled and /issues/{index}/dependencies 404 not found, while the entries are kept and read again once the feature is back on; a missing issue answers 404 as well (issue does not exist), so a reader checks the repository's internal_tracker before reading these lists. PATCH /repos/{owner}/{repo} applies internal_tracker only beside has_issues: true and otherwise answers 200 without a change
  • internal: true marks a public repository of a private owner; a public repository of a limited organization reports internal: false
  • private repositories are invisible (404) to anonymous callers, and a non-administrator token is refused on admin endpoints (403)
  • a whole-repository team reports its permission and a null units_map; a granular team reports permission: none and its access in units_map. The Owners team reports owner
  • an archived repository answers 404 on its pull request routes, reads included (go-gitea/gitea#39155)
  • a repository without a wiki answers 404 on its wiki page list
  • a protected main refuses commits through the contents API (403), even for the administrator
  • release asset names are stored as given: spaces and parentheses, non-ASCII characters, a leading dot, and the same name twice in one release
  • a release creates its tag, a draft does not
  • release assets download from /attachments/{uuid} with the administrator's token, without a redirect
  • a branch protection keeps no allowlisted user without write access, and Gitea still answers 201
  • /collaborators/{username}/permission reports the effective access mode, never the collaboration's own mode, which no REST endpoint reports: a site administrator reads owner, an Owners member owner, and a collaboration below a team's mode reads the team's mode. It answers for non-collaborators too and reports one access mode only: a granular team's units do not show (a member reads the public read), and a restricted member whose only access to a public repository of a private organization is a team read reads none
  • a sign-in-prohibited account stays active, and a restricted or sign-in-prohibited collaborator keeps the collaboration's mode
  • every Owners team is includes-all, may create repositories, is limited (listable by members) and, unlike a whole-repository team, reports a units map: owner on every unit except read on the external issue tracker and wiki. A team created without a visibility is private
  • an includes-all team created after the repositories holds all of them
  • SSH keys of type ssh-ed25519, ssh-rsa (3072 bits; the default minimum is 3071 per modules/consts/asymkey.go, not probed), ecdsa-sha2-nistp256, sk-ssh-ed25519@openssh.com and sk-ecdsa-sha2-nistp256@openssh.com are accepted; a fingerprint is OpenSSH's SHA256: digest of the key blob
  • a fingerprint belongs to one public key row: Gitea refuses (422, Key content has been used as non-deploy key) a user key as a second user's key or as a deploy key, and a deploy key as a user key; the same key twice on one repository answers 422 This key has already been added to this repository, and a second deploy key or token with a taken title 422 A key with the same name already exists
  • one public key as a deploy key on several repositories is one shared key row (equal key_id and fingerprint) with a deploy key, and its own mode, per repository; the row survives the removal of a binding and is deleted with the last one
  • /repos/{owner}/{repo}/keys lists deploy tokens beside SSH deploy keys with key_type: token, key_id: 0, an empty key and a fingerprint that masks the token (gdt_, two characters, ********, the last two); only the create response carries the token (gdt_ and 43 alphanumerics)
  • a deploy token, as the password (any user name) or as the user name (an empty or any password) of HTTP Basic, authenticates Git over HTTPS for its own repository only (another private repository answers 404, the REST API 401); a read-only token receives the push advertisement but the push is refused by the pre-receive hook

The default seed's packages (asserted in test/test.gitea.packages.node.ts), with these Gitea 28.2.0 facts:

  • packages of every registry the migration carries: generic tool (linked to public-repo), pallet-build-inputs (Pallet's pins __NR_riscv_hwprobe.patch and __stack_chk_fail_local.c, each version the SHA-256 of its file) and odd-names (a space, # and %, one content under three names in two versions) of team-with-hyphens, and internal-tool of the private private-org; the container image team-with-hyphens/app (linked); the user-owned image alice/tools/cli; the Docker-format image limited-org/legacy; the npm packages @team-with-hyphens/client (linked), next-only and beta-only; the Swift package fixtures.swiftsupport (1.0.0, 1.1.0, and 1.2.0 with the root alternate 5.10 and the nested alternate 6.0); the Cargo crate fixture-crate
  • the v1 package API reports the version id as id and carries no package id: two versions of one package read different ids
  • a container version is a tag, lowercased (Latest reads latest), or the digest sha256:<hex> of a manifest pushed by digest; app holds the tags 0.9.0, 1.0.0, edge and latest and four untagged manifests: the three children of the index, one of them an attestation manifest, and an orphan no index names
  • an index version holds only its manifest.json; an image version holds its manifest.json and its config and layers as sha256_<hex> files. One index under two tags is two versions holding one content
  • pushing a tag again deletes the version it named: the earlier manifest answers 404 and no version lists it
  • tags/list without n lists every tag
  • a manifest is served with its exact bytes, the media type it was pushed with as Content-Type (OCI and Docker manifests, OCI index and Docker manifest list) and its digest as Docker-Content-Digest
  • a layer pushed to three owners (a public and a limited organization and a user) reads back with one SHA-256 in each
  • an anonymous GET /v2/ answers 401 with exactly WWW-Authenticate: Bearer realm="<origin>/v2/token",service="container_registry",scope="*"; an anonymous GET /v2/token returns a token, with which /v2/ answers 200 and a public image's manifest is served; Basic credentials answer 200 on /v2/; POST /v2/token answers 404
  • generic package names, versions and file names are looked up case-insensitively, and files of a public owner download anonymously by their percent-encoded names; a private organization's file answers 401 to an anonymous request
  • npm: a package published without latest still lists one in its dist-tags and package document, and Gitea stores no latest tag for it: it derives the highest version without a prerelease part (next-only: 0.2.0, though 0.3.0-rc.1 is higher and 0.1.0 was published last), or the highest prerelease when every version is one (beta-only: 1.0.0-beta.10 above 1.0.0-beta.2). No read tells a derived latest from a stored one, so the manifest records every dist-tag Gitea serves (S10 ruling, Addendum 2); the package document carries a version's deprecation message and none for a version that is not deprecated, and advertises tarballs at {package}/-/{file}, while {package}/-/{version}/{file} serves the same bytes
  • Swift: the release list, the release metadata (the source archive's SHA-256 as its checksum, description and repository URLs), Package.swift and the identifier lookup by repository URL
  • Swift manifests: Gitea keeps only the manifests of the shallowest directory that holds one (modules/packages/swift/metadata.go), so 1.2.0 serves 5.10 from beside Package.swift and answers 303 to the release's own Package.swift for 6.0, which only the nested package holds; the stored archive holds both files. Without swift-version the route serves Package.swift, and a requested version is trimmed like the keys (5.10.0 reads 5.10)
  • Cargo: the sparse index line of each version carries its dependencies, features, the crate's SHA-256 as cksum and yanked; config.json names the download and API URLs and auth-required: false for a public owner; crates download through api/v1/crates/{name}/{version}/download
  • reads write almost nothing: over the inventory and transfer read paths (the v1 package listings, version reads and file lists, /v2/token, /v2/, tag lists, manifest HEADs and GETs by digest, blob HEADs and GETs, generic file HEADs and GETs, npm dist-tags, package and version documents and tarballs in both forms, Swift release lists, metadata, Package.swift for every recorded key and its 303 for a nested one, archives and identifier lookups, Cargo config.json, sparse index lines and crate downloads), no entry below the data directory changes, no row is inserted or deleted, and the only values that move are package_version.download_count and updated_unix of the administrator token's row, which the test pins as the one token stamp. A GET of a lead file counts one download of its version: a manifest by digest (an index read for its children included), a generic file, an npm tarball, a Swift archive and a crate. HEAD, the blob GETs of configs and layers and the Swift manifest route count nothing. A read of a manifest that two tag versions hold counts one download across them. Both are known read stamps: download counts under S10 ruling item 8, and the token's last use, accepted by S10 ruling Addendum 2. The same comparison sees a deprecation (package_version.metadata_json), an upload (new rows and package files) and a commit (new Git objects below git/repositories, outside every package store)

The default seed's v1.0.0 release carries a SHA256SUMS asset in sha256sum format (<hex> <name> per line) covering its other assets, among them a 5 MiB + 1 byte asset of deterministic bytes; the prerelease carries the odd and duplicate names, the draft carries its own SHA256SUMS beside draft.txt, and the private repository's release and the archived repository's release carry plain assets without a digest list. The release/* branch rule sets every field away from its default; the v* tag rule allows alice and the maintainers team.

GitLab seed specs and manifests

GitlabSeedBuilder.apply(spec) validates the whole spec before the first request, then creates, as the root administrator unless noted:

  • users (with random, discarded passwords), groups and nested subgroups with public, internal or private visibility, and group members
  • projects in groups or personal namespaces, initialised with a README on main, plus project members
  • files on main, branches created by one commit each, labels, milestones and tags
  • issues (including confidential issues and incidents) and merge requests, authored through the administrator's Sudo header; labels, milestones, assignees and closing are applied by the administrator, and the seed fails if GitLab does not apply them
  • releases, and closing of milestones marked closed
  • deletion of the users listed in deleteUsers, last, waiting until GitLab finished moving their contributions to its ghost user

The returned IGitlabSeedManifest is read back after all mutations: group and project IDs, namespaces, visibility, web_url and clone URLs, branch commits, every tag the project holds (releases create their own tags) with its commit, labels, milestones, issue and merge request IDs and IIDs, states, types, confidentiality, authors (after deletion), assignees, notes and releases.

createDefaultGitlabSeedSpec() creates 25 projects, more than one default page of 20. These are observed facts of GitLab CE 19.4.1, asserted by the opt-in test or handled by the seed:

  • issues and merge requests have separate IID sequences per project
  • a deleted user's issues and notes are reattributed to the ghost user; the deletion runs in the background and took about 50 s
  • a closed milestone assigned through the API is silently ignored (the milestone finder defaults to active milestones), so the seed closes milestones after assigning them
  • group members get access to a project created in the group from a background job, so a member can see 404 for a few moments; the seed waits for access before acting as that member
  • keyset pagination Link headers carry the fixture origin
  • internal projects are 404 to anonymous callers and visible to any signed-in user; private projects and confidential issues are 404 to non-members; a non-administrator token is refused on admin endpoints (403)

Ownership and Cleanup

Every container, network and volume of a lifecycle carries labels under global.foss.forgefixtures.*: the lifecycle ID, fixture kind, machine ID (/etc/machine-id; a process whose system has none, as in many container images, uses a random ID fixed for its lifetime), host name, kernel boot ID, owner PID namespace (pid:[<inode>]), owner PID, owner process start time, creation time and expiry. Before starting, each lifecycle runs the reaper, which removes a lifecycle's resources when:

  • its maxLifetimeMs (default two hours) has passed (expired)
  • its owner ran on this machine, and the machine rebooted since (owner-rebooted)
  • its owner ran on this machine in the reaper's own PID namespace, and that PID no longer exists or belongs to a process with a different start time (owner-exited)

A PID identifies a process only inside its PID namespace. Processes that share the Docker socket can share host name and boot ID without sharing PIDs, for example a runner in a host-network container, and machines sharing a remote daemon can share a host name. Owners with another machine ID or host name, or in another PID namespace, are therefore judged by expiry only. A process without a machine ID therefore judges every other owner by expiry only, and every other process judges its owners the same way. Resources whose labels cannot be interpreted, including labels without a machine ID or PID namespace, are reported and never removed. Gitea seed snapshots carry their own labels (global.foss.forgefixtures.snapshot.*, and the staging lifecycle's owner labels on the volume) but no managed label, so they outlive the lifecycle that stored them; the reaper's snapshot pass removes those of another forgefixtures release or Gitea image and staged volumes whose stager is stale, and leaves a volume another container still mounts for a later pass, such as one a restore helper holds; a start whose snapshot was evicted before its helper held it seeds instead. The reaper can also be run on its own:

import { ForgeFixtureReaper } from '@foss.global/forgefixtures';

const report = await new ForgeFixtureReaper().reap();
console.log(report.reapedLifecycles, report.unrecognizedResources);

Pinned Images and Resources

Fixture Image Limits
Gitea gitea/gitea:28.2.0-rootless@sha256:94807314454f6525994a3b76286ba12bc7e7f8cd14f61d9e67431767f8103306 (multi-architecture index) 512 MiB memory without swap, 2 CPUs, 512 PIDs
Gitea SSH sidecar (ssh option) gitea/gitea:28.2.0@sha256:30777c91280d973fa02be48b1ade735bd6859e8f6f7af3b4444d519437852504 (multi-architecture index; giteaFixtureSshImage, the same release as the Gitea pin, not part of the snapshot key) 256 MiB memory without swap, 1 CPU, 128 PIDs, no capabilities
GitLab CE gitlab/gitlab-ce:19.4.1-ce.0@sha256:9b33b45b9f42d176bada85ee5ecb81ddab7e506c435f44cd582206e284b2809c (multi-architecture index) 5 GiB memory without swap, 4 CPUs, 4096 PIDs, 256 MiB /dev/shm

Images are pulled by digest and the pulled repository digest is verified; a moved tag cannot change what runs. Gitea runs as uid 1000 with SQLite, and its data directory, configuration and Git hooks live in one owned named volume that is removed with the lifecycle; hooks must be executable, which Docker's noexec tmpfs mounts would prevent. Only the plain-HTTP port is published, on 127.0.0.1, on a port the lifecycle picks from the kernel's free loopback ports (a rootless daemon allocates ephemeral ports blind to host listeners); with the ssh option the sidecar's sshd port is published the same way. The sidecar is a second container of the same lifecycle, with its labels, removed first by stop() and by the reaper.

GitLab runs as root inside the container, which a rootless daemon maps to the invoking user. Its configuration, data and logs live in three owned named volumes that are removed with the lifecycle. Run one GitLab fixture at a time and check the host's available memory first: the opt-in test refuses to boot GitLab with less than 8 GiB available.

Measured on a 32-CPU host with the image already present:

  • Gitea: start to ready in 7–10 s, the default seed in 9–14 s, about 170 MiB of memory while idle after seeding, and a 3.6 MiB data volume.
  • Gitea seed snapshots (2026-11-14, load average 25–35 on a shared host): a seed start that seeds the default spec took about 24–26 s of seedReport.durationMs (seed, settle, store, restart); a restoring start spent about 1 s finding, checking and extracting the snapshot. The default seed's data directory is about 10 MiB.
  • Freeze controls (2026-11-15, load average about 20 on a shared host): a seed start of giteaFreezeCanarySeed with ssh and secondOrigin seeded in about 5 s of seedReport.durationMs and was ready in about 13 s; a restoring start with the sidecar in about 4–6 s. The three freeze groups ran in 11.6–22.8 s (origins), 16.8–17.8 s (stack) and 14.7–17.1 s (hook) per file, the first including the seed; a freeze restart takes about 2 s.
  • GitLab CE (four runs): start to ready in 253–269 s, the default seed in 63–138 s (about 50 s of it waiting for the user deletion), a token created through gitlab-rails runner in up to a minute. Anonymous memory is about 2.8 GiB while idle after seeding and peaked at 3.6 GiB while a token runner shared the container with Puma; a 4 GiB limit was reached through page cache (reclaimed by the kernel, no OOM kills), so the default limit is 5 GiB to leave headroom for anonymous memory peaks. After seeding the data volume holds 486 MB, the log volume 11 MB and the configuration volume 0.2 MB. The image is 3.8 GB.

Tests

pnpm test runs the Docker-free tests only. The Docker tests are opt-in; the Gitea suite also clones and pushes with the host's git:

FORGEFIXTURES=gitea pnpm exec tsrepo test test/test.gitea.node.ts --verbose --logfile
FORGEFIXTURES=gitea pnpm exec tsrepo test test/test.gitea.packages.node.ts --verbose --logfile
FORGEFIXTURES=gitea pnpm exec tsrepo test test/test.gitea.crash.node.ts --verbose --logfile
FORGEFIXTURES=gitea pnpm exec tsrepo test test/test.gitea.restore.node.ts --verbose --logfile
FORGEFIXTURES=gitea pnpm exec tsrepo test test/test.gitea.freeze.origins.node.ts --verbose --logfile
FORGEFIXTURES=gitea pnpm exec tsrepo test test/test.gitea.freeze.stack.node.ts --verbose --logfile
FORGEFIXTURES=gitea pnpm exec tsrepo test test/test.gitea.freeze.hook.node.ts --verbose --logfile
FORGEFIXTURES=gitea pnpm exec tsrepo test test/test.gitea.pulls.node.ts --verbose --logfile
FORGEFIXTURES=gitlab pnpm exec tsrepo test test/test.gitlab.node.ts --verbose --logfile

FORGEFIXTURES takes a comma list (gitea,gitlab) or all. All GitLab assertions live in one file, so GitLab boots fully once per run; that file also stops three GitLab starts at different phases, one at a time.

test.gitea.packages.node.ts seeds the default spec in its own fixture and asserts the package facts above, including the state comparison over every read path and its positive control.

test.gitea.restore.node.ts seeds a run-unique default spec through the seed option, restores it in a second fixture and compares the two (see Seeded starts and snapshots), then removes its snapshot.

The three freeze files are one fixture group each, every one starting its own giteaFreezeCanarySeed fixture (the first seeds, later starts restore): test.gitea.freeze.origins.node.ts proves the canary's preflight reads and that every control is accepted on both origins while Gitea is open, with each origin's requests arriving on its own address; test.gitea.freeze.stack.node.ts disables a registered runner, restarts with the freeze settings, sets the hook and the filter with one nonce, proves every canary on both origins is refused with it while reads go on, then lifts the stack and proves writes are accepted again; test.gitea.freeze.hook.node.ts proves the hook alone refuses the SSH push (and the HTTPS push) with the nonce, keeps fetches and survives a restart. test.gitea.readstamps.node.ts starts a fourth one and proves that token reads and SSH and HTTPS fetches change nothing but giteaReadStampFields.

test.gitea.pulls.node.ts is one fixture group: it writes giteaPullRequestArchiveSeed with GiteaSeedBuilder.apply (a builder test never restores a snapshot of the same version) and asserts the pull request facts on the manifest and against Gitea; it ran in 17.6 s on 2026-11-15 at a load average of about 50 (seed about 7.8 s).

test.gitea.crash.node.ts starts a fixture in a child process that kills itself with SIGKILL, then proves the reaper removes the container, network and volume that outlived it.

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the license.md file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

Company Information

Task Venture Capital GmbH
Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

S
Description
No description provided
Readme MIT
2.5 MiB
0 Stars 3 Watchers 0 Forks
Languages
TypeScript 100%