@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
dockerSocketPathoption, otherwiseDOCKER_HOST, otherwise/var/run/docker.sock - for GitLab, a rootless Docker Engine: the omnibus image runs as root, and
@apiclient.xyz/dockerpermits a root container user only after the daemon proves rootless mode.GitlabFixturedefaults 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 throughGiteaSeedBuilder.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.seedManifestis the manifest the seeding run read back, with its per-run fields,baseUrland every repository'shtmlUrlandcloneUrl, 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 itsROOT_URLline only (the image's entrypoint writes the environment into it at every start); LevelDB's info logqueues/common/LOG; and the Bleve store rootindexers/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, itscompare_urlamong 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 fromhttp://localhost:3000, inside the container, somirror-syncworks after a restore, also into asecondOriginfixture whoseROOT_URLnameslocalhostwhere the seeding run's named127.0.0.1(probed 2026-11-15); webhooks keep their spec URLs; release asset and package URLs (the npmtarballincluded) are derived fromROOT_URLwhen 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
409volume 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, sogitlab-ctl reconfigurefinished - Docker reports the container healthy through the image's own
gitlab-healthcheck, gated on that hook - an unauthenticated
/api/v4/versionanswers 401 through the proxy, so nginx, Workhorse and Puma serve the API - an administrator token exists and
/api/v4/versionreports 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/sshandLOCAL_ROOT_URL=http://gitea:3000/, and its container answers to the network aliasgiteaon the lifecycle's network (also when a restart re-creates it). Gitea therefore keepsauthorized_keysfor OpenSSH in its data directory instead of running its own SSH server, and every snapshot'sauthorized_keysmatches its database.SSH_PORTis Gitea's default, so thessh_urlGitea 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 nosshd) after the seeded state is ready:sshd(OpenSSH 10.3p1 on Alpine) as uid 1000 with every capability dropped andno-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 usergitby public key from Gitea'sauthorized_keys, whose forced command runsgitea serv. Its port 2222 is published on127.0.0.1;start()returns once that port has sent anSSH-2.0-banner. Production runs OpenSSH as root with privilege separation; the forced-command path and theremote:messages are the same.sshEndpointthrows without the option or while the fixture is not running.secondOrigin(default off) makes the TLS proxy listen on127.0.0.1and on127.0.0.2on the same port (on a port taken on127.0.0.2it picks another, at most three times, then throws naming both addresses), with one certificate (it nameslocalhost), one filter state and one request log.runtime.baseUrl, Gitea'sROOT_URLandseedManifestnamehttps://localhost:<port>; a client reaches the second origin by connecting to127.0.0.2for that host name (Git:http.curloptResolve=localhost:<port>:127.0.0.2).127.0.0.2binds on Linux without configuration (macOS needs a loopback alias). Without the option the base URL stayshttps://127.0.0.1:<port>with one listener.originsthrows without the option or while the fixture is not running.setFreezeHook(message | null)writes apre-receivehook and its message to/var/lib/gitea/freeze-hooksin the data volume (never a tmpfs, so a restart keeps it) and pointscore.hooksPathin 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 withpre-receive hook declinedand the message as aremote:line; fetches go on.nullunsetscore.hooksPathand removes the directory.setEdgeFilter({ marker? } | null)applies the freeze runbook's HTTP allowlist in the TLS proxy, on both origins:GETandHEADpass 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);POSTpasses only forgit-upload-packand the Git LFS batch endpoint; everything else (the LFS objectPUT, the runner API, every API write) is answered503withRetry-After: 3600, the marker inX-Gitea-Freezeand 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):truesaves Gitea's configuration beside it once and writes[cron] ENABLED=false,[mirror] ENABLED=falseand[server] LFS_ALLOW_PURE_SSH=falseinto it throughgitea config edit-ini, then restarts Gitea:/api/v1/admin/cronlists no scheduled task andupdate_mirrorsis gone.falseputs the saved configuration back and restarts, so Gitea's defaults apply again (writingENABLED=trueinstead 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 asact_runner registerdoes: a token fromgitea actions generate-runner-token, then the runner API'sRegistercall (Connect-Protocol-Version: 1). It returns{ id, uuid, name }as/api/v1/admin/actions/runnerslists it; the runner's credentials are dropped, it never polls (statusoffline, 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'withmerged: true,merged_bythe user who merged andmerge_commit_shathe base branch's new head - once its branch is deleted, a pull request's
head.refreadsrefs/pull/<number>/head, whilehead.labelkeeps the branch name andhead.shathe last head commit; the branch answers 404 - a pull request from a fork names the fork in
head.repoand its branch's commit inhead.sha - the review list shows a site administrator every review, other users'
PENDINGdrafts 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 stateREQUEST_REVIEW; a dismissed review keeps its state withdismissed: true; Gitea dismisses only approvals and change requests of an open pull request and has no dismissal message field requested_reviewersis 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 isis_locked, and organization labels reach it as they reach issues - the merge route answers 405
Please try again laterwhile the mergeability check Gitea queues at creation runs, so the builder waits formergeable
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,-1for Gitea's default) and organization creation (allowCreateOrganization), with generated SSH keys (a plain title is Ed25519;{ title, algorithm }picksed25519,rsa,ecdsa-p256,sk-ed25519orsk-ecdsa-p256; private halves are discarded unless an Ed25519 key setskeepPrivateKey), and access tokens (accessTokens: a name and Gitea 28 scopes, neverall, neverreadbesidewriteof 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 withpublic,limitedorprivatevisibility, an optional display name, description and website, optional extra members of theirOwnersteam, 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 withALLOWED_HOST_LIST=loopback:*), plus collaborators withread,writeoradmin - 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
Sudoheader; 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 throughSudo. Issue and comment attachments are uploaded by their author; a comment'seditedBodyreplaces its body in a later second than its creation, so the edit shows inupdated_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 verbatimref, boards of their repository and organization, tracked times added through the user'sSudo, 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;lockedissues are locked by the administrator after every other step - pull requests (
kind: 'pullRequest') opened through the author'sSudofrom a branch of the repository or, withheadRepository, 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'sSudo(stateCOMMENTby default,APPROVED,REQUEST_CHANGESorPENDING, 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 markeddismissed(approvals and change requests only), review requests (requestedReviewers, read back asREQUEST_REVIEWreviews), the close or, forstate: 'merged', the merge with Gitea'smergestyle throughmergedBy'sSudo(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 thenamequery 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
.gitattributesLFS 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
sharedKeylabel 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
Ownersmembers, 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, aTGiteaSeedPackageunion ontype), 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 byPUT; file names may hold spaces,#and%, as Gitea's file name rule allowscontainer: 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 itstags, or by its digest when it has none. An image manifest (OCI or Docker schema 2 media types) has a JSON config for itsplatformand 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, withformat: 'docker', a Docker manifest list) lists image manifests declared before it;attestationFormarks a child as another child's attestation manifest with BuildKit's annotations. A tag pushed again movesnpm: versions published likenpm publish --tag(defaultlatest), thendistTagsthrough the dist-tags API anddeprecationslikenpm 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 asscope.name. A version'salternateManifestsaddPackage@swift-<swiftVersion>.swiftfiles, written as Gitea keys them (5.10,5.10.1, never5.10.0), each besidePackage.swift(root) or in the nested package directory<name>/Tests/Fixtures/(nested); a key appears once per version, and at most 63 alternates sit besidePackage.swift, because Gitea keeps at most 64 manifestscargo: versions published through the Cargo publish API with their dependencies and features, then yanked whereyankedis setlinkRepositorylinks 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 holdcodeand 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 indeleteUsers, 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: inpublic-repo, #4 carries the organization labelneeds-triage, #5 a comment edited after its creation (itsupdated_atis later than itscreated_at), #6 the closed title' Title with outer spaces 'and #7 the bodyTracked as limited-org/limited-repo#1.; inlimited-org/limited-repo, which the foss.global e2e never publishes, #2 an issue attachmentnotes.txtand a comment attachmentbuild.log, #3 a lock and #4 the due date2027-03-15T23:59:59Zin the milestoneq1-2027, due2027-03-31T23:59:59Z - a reference to another repository's issue is resolved when it is written: #7 was written before
limited-repoexisted, and that repository's #1 has noissue_refevent 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 refrefs/heads/mainand the exclusive labelarea/backend(the repository also has the archived labellegacy), #6 the boardsRepository board(typerepository) andOrganization roadmapoflimited-org(typeorganization), #7 a time estimate of 5400 seconds (achange_time_estimateevent), #8 a 1800-second tracked time ofalice, #9 a dependency on #5, #10 pinned (pin_order1); every other issue keeps'', no boards,0and 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}/projectsneedsread:organization,/users/{username}/projects(an organization's boards too)read:user,/repos/{owner}/{repo}/projectsonlyread:issue; a site administrator passes the Projects unit check. Anonymous callers read a public user's boards and get 404 for alimitedorganization and its repositories - with time tracking or dependencies switched off for a repository,
/issues/{index}/timesanswers 404timetracker is disabledand/issues/{index}/dependencies404not 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'sinternal_trackerbefore reading these lists.PATCH /repos/{owner}/{repo}appliesinternal_trackeronly besidehas_issues: trueand otherwise answers 200 without a change internal: truemarks a public repository of a private owner; a public repository of alimitedorganization reportsinternal: 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
permissionand a nullunits_map; a granular team reportspermission: noneand its access inunits_map. TheOwnersteam reportsowner - 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
mainrefuses 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}/permissionreports the effective access mode, never the collaboration's own mode, which no REST endpoint reports: a site administrator readsowner, anOwnersmemberowner, 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 publicread), and a restricted member whose only access to a public repository of a private organization is a team read readsnone- a sign-in-prohibited account stays active, and a restricted or sign-in-prohibited collaborator keeps the collaboration's mode
- every
Ownersteam is includes-all, may create repositories, islimited(listable by members) and, unlike a whole-repository team, reports a units map:owneron every unit exceptreadon the external issue tracker and wiki. A team created without a visibility isprivate - 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 permodules/consts/asymkey.go, not probed),ecdsa-sha2-nistp256,sk-ssh-ed25519@openssh.comandsk-ecdsa-sha2-nistp256@openssh.comare accepted; a fingerprint is OpenSSH'sSHA256: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 422This key has already been added to this repository, and a second deploy key or token with a taken title 422A key with the same name already exists - one public key as a deploy key on several repositories is one shared key row (equal
key_idand 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}/keyslists deploy tokens beside SSH deploy keys withkey_type: token,key_id: 0, an emptykeyand 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 topublic-repo),pallet-build-inputs(Pallet's pins__NR_riscv_hwprobe.patchand__stack_chk_fail_local.c, each version the SHA-256 of its file) andodd-names(a space,#and%, one content under three names in two versions) ofteam-with-hyphens, andinternal-toolof the privateprivate-org; the container imageteam-with-hyphens/app(linked); the user-owned imagealice/tools/cli; the Docker-format imagelimited-org/legacy; the npm packages@team-with-hyphens/client(linked),next-onlyandbeta-only; the Swift packagefixtures.swiftsupport(1.0.0,1.1.0, and1.2.0with the root alternate5.10and the nested alternate6.0); the Cargo cratefixture-crate - the v1 package API reports the version id as
idand carries no package id: two versions of one package read different ids - a container version is a tag, lowercased (
Latestreadslatest), or the digestsha256:<hex>of a manifest pushed by digest;appholds the tags0.9.0,1.0.0,edgeandlatestand 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 itsmanifest.jsonand its config and layers assha256_<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/listwithoutnlists 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 asDocker-Content-Digest - a layer pushed to three owners (a public and a
limitedorganization and a user) reads back with one SHA-256 in each - an anonymous
GET /v2/answers 401 with exactlyWWW-Authenticate: Bearer realm="<origin>/v2/token",service="container_registry",scope="*"; an anonymousGET /v2/tokenreturns a token, with which/v2/answers 200 and a public image's manifest is served; Basic credentials answer 200 on/v2/;POST /v2/tokenanswers 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
lateststill lists one in its dist-tags and package document, and Gitea stores nolatesttag for it: it derives the highest version without a prerelease part (next-only:0.2.0, though0.3.0-rc.1is higher and0.1.0was published last), or the highest prerelease when every version is one (beta-only:1.0.0-beta.10above1.0.0-beta.2). No read tells a derivedlatestfrom 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.swiftand 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), so1.2.0serves5.10from besidePackage.swiftand answers 303 to the release's ownPackage.swiftfor6.0, which only the nested package holds; the stored archive holds both files. Withoutswift-versionthe route servesPackage.swift, and a requested version is trimmed like the keys (5.10.0reads5.10) - Cargo: the sparse index line of each version carries its dependencies, features, the crate's SHA-256 as
cksumandyanked;config.jsonnames the download and API URLs andauth-required: falsefor a public owner; crates download throughapi/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, manifestHEADs andGETs by digest, blobHEADs andGETs, generic fileHEADs andGETs, npm dist-tags, package and version documents and tarballs in both forms, Swift release lists, metadata,Package.swiftfor every recorded key and its 303 for a nested one, archives and identifier lookups, Cargoconfig.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 arepackage_version.download_countandupdated_unixof the administrator token's row, which the test pins as the one token stamp. AGETof 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 blobGETs 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 belowgit/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,internalorprivatevisibility, 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
Sudoheader; 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
ghostuser; 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
Linkheaders 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
seedstart that seeds the default spec took about 24–26 s ofseedReport.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
seedstart ofgiteaFreezeCanarySeedwithsshandsecondOriginseeded in about 5 s ofseedReport.durationMsand 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 runnerin 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.
License and Legal Information
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.