Docs

The repo's icon: one PNG, WebP or SVG file, by its name's extension; anything else is rejected.

For metadata-only repos: a directory of files browsable in place of the code by everyone who can't read it (its README.md is the landing page). Built only for those repos.

What CI does for a ref: a function of the ref (its full name, e.g. refs/heads/main) and the commit (rev), evaluated for every pushed ref. Read from the commit's own flake.

Outputs for downloading (images, archives, firmware, reports): a single file, or a directory whose files are listed and downloaded one by one. One that references other store paths is rejected, unless selfContained is off.

Outputs for Nix: their closures are served by the binary cache.

Derivations (for any system) to build: they succeed or fail, nothing more. Anything but a derivation is rejected.

Impure jobs: deployments, updates, notifications.

One sops-encrypted file for all of the CI, encrypted to the repo's age key (gtd keys repo-recipient <repo> on the host). Effects receive the keys they list in secrets.

Shown instead of the attribute name.

The store path (a derivation's output) to publish.

Offered to everyone who can see the repo's CI, not only readers. No effect on private repos.

Whether it must not reference other store paths (anything else is rejected): what a published script or report should be. Off, it may (e.g. a symlinkJoin), and the files its symlinks lead to in its closure are listed and served with it.

Also serve what building it built here: the outputs of every derivation in its build closure that this host built itself (toolchains, generators, …), not those it downloaded. Sources and .drv files are never served.

Shown instead of the attribute name.

The store path (a derivation's output) to publish.

Offered to everyone who can see the repo's CI, not only readers. No effect on private repos.

Instead of drv: an approval step, which a writer of the repo approves or denies. It passes the outputs of its needs on unchanged, and must have needs.

How long it waits for a decision before it expires (and what needs it is skipped): seconds, or a number with s, m, h, d or w.

What the approver is asked.

Shown next to its name.

What runs: a derivation whose executable (its meta.mainProgram, or the file itself) is run in a sandbox, in a checkout of the commit, with:

• /run/gt/secrets/<key path>: the listed secrets;
• /run/gt/trigger.json: what started it (push, schedule or webhook), the ref, the commit and the chain that led here;
• /run/gt/webhook/: a webhook call's body and headers (untrusted input);
• /run/gt/in/<effect>/: the outputs of the effects it needs.

It may write:

• /run/gt/out/: outputs for the effects that need it (summary.md is shown on the approvals that follow, each under the name of the effect that wrote it);
• /run/gt/result.json: a small structured result;
• /run/gt/skip: marks the run as skipped (its content: why).

Either drv or approval.

It gets a clone with history, the branch checked out, and may commit: after a successful run, if its branch is a strict descendant of where it started and the branch hasn't moved since, the branch is advanced to it (the repo must allow it too: ci.allowFastForward on the host). That counts as a push, so CI runs on it. Only its own branch, never tags.

What it deploys, linked from it.

Effects it waits for, in the same run on the same commit, and whose outputs it receives (/run/gt/in/<effect>/). If one fails, this one is blocked (doesn't run); if one is skipped (or an approval is denied or expires), so is this one.

When it runs. Unset: on push; set, only on what it lists. Effects with needs run with what they need instead, and have no on.

Runs when a ref it is declared on is updated, on the new commit (branches and tags).

Runs on the branch's tip at these times. Branches only; missed times aren't made up for.

Five cron fields (minute resolution).

An IANA time zone.

Runs when POST <web URL>/<repo>/-/hooks/<effect>/<branch> is called with a token whose hash the host has for it (repos.<repo>.webhookTokens.<effect>). Branches only.

Keys of secretsFile it receives, as /-separated paths into the file's nested keys.

On a push, wait until none of the branch's fast-forwarding effects is queued or running: if they changed nothing, run on the pushed commit; if they fast-forwarded, run once on the new tip instead.

Host name of the Nix binary cache.

Configure Caddy as the reverse proxy.

Separate host name for untrusted content (raw files, artifacts).

Branch HEAD points to in newly created repos.

The option docs served at /-/docs (the flake's docs package). Unset: no docs.

Whether to enable gt, a small Nix-native code host.

The bundled frontend assets.

SSH host key (ed25519): root of trust for per-repo age keys.

Host name of the web UI.

The site's logo in the page top (SVG, PNG or WebP). Unset: a plain placeholder.

The gt package (both binaries).

Port in the public URLs, when clients reach Caddy on a non-default port (e.g. through a port forward).

Base of SSH clone URLs shown in the UI, as git@host:repo.git when it has no port other than 22.

Serve over HTTPS (Caddy's automatic TLS). Disable for *.localhost.

Whether to enable a local Valkey page cache for public pages.

systemd IPAddressAllow= (takes precedence), e.g. your DNS resolver.

systemd IPAddressDeny= for effect units.

How long an effect may run before it's stopped (and fails).

systemd IPAddressAllow= (takes precedence): systemd-resolved's stub resolver by default; add another local resolver here.

systemd IPAddressDeny= for the scheduler, where flakes are evaluated: their fetches get the internet, not the host's own services.

systemd IPAddressAllow= (takes precedence) for the image proxy: its DNS resolver (systemd-resolved's stub by default).

systemd IPAddressDeny= for the image proxy, which fetches documents' external images for viewers: the internet, never the host or its networks (it refuses those addresses itself too).

Builds at once.

Links in a chain of fast-forwards (the push, then each effect whose fast-forward led to the next): beyond it, push effects are skipped, so effects can't keep each other going.

Bytes an effect may write to /run/gt/out/; more fails it.

Files an effect may write to /run/gt/out/; more fails it.

Effects running at once.

CPU time one evaluation may use; more fails it (and it's stopped after twice that, plus 30 seconds, of wall time).

Memory one evaluation may use; more fails it.

Evaluations at once.

Heavy work at once on the machine, of all its processes: commit caches, search indexes, histories put in order ahead of visitors. One slot is kept for the short kind, so a search index taking hours (nixpkgs') doesn't hold up the rest.

Results of one search, per kind (code, commits, diffs).

Bytes of a webhook call's body; a larger call is refused.

Repositories, by name, or by pattern for many: * stands for one or more characters within a path segment. Every entry that applies to a repo counts: readers, writers and accessFrom add up; other settings come from the most specific one setting them (the repo's own, then the pattern with the most fixed characters). Writers of a pattern create repos by pushing to a new matching name; a repo shows up once it has commits.

Repos (names or patterns) whose CI may read these repos, e.g. as private flake inputs. "*".accessFrom = [ "*" ]: every repo's CI may read every repo.

Allow effects with fastForward = true to advance branches.

Evaluate the flake's ci and run builds and effects. Unset: as a less specific pattern says, else off.

The branch HEAD points to (master, or refs/heads/master): the default branch clones check out, and what the overview, log and CI follow. Set when the branch exists (as the config changes, and on pushes). Unset: as a less specific entry says, else where it points (a repo created by a push points to a branch it pushed).

Remotes this repo is pulled from, by name: like pushes, their changes run CI and go on to the push mirrors. A repo that only pulls needs nobody to push; it's created on its first pull. Only on a repo's own entry, not on patterns.

The one upstream branch to pull. Unset: all branches and tags.

Also take updates that aren't fast-forwards (and moved tags), replacing what's here.

Seconds between pulls. Null: only when the webhook is called (and once when gt starts).

With branch: the local branch it updates. Unset: the same name.

With all branches: delete branches and tags that aren't upstream (pushed ones too), keeping the repo an exact copy.

Where to pull from. Over SSH, with a key of its own (shown to readers on the overview: add it as a deploy key there).

Where people see it: linked from the overview, for everyone.

Token name -> sha256:<hex> (see gtd keys token). A POST to <web URL>/<repo>/-/pull/<name> with one of them (as a Bearer token or ?token=) pulls right away.

Remotes every change is pushed on to (branches and tags, exactly), by name. Each gets an SSH key of its own (shown with its pushes to readers of the repo: add it as a deploy key there); the private half stays on the host, encrypted to the host key.

Where to push.

Where people see it: linked from the overview, for everyone.

Seconds what's published (artifacts, caches, meta) is kept after it was last published; publishing it again, by a later commit building the same thing, starts over. Unset: as a less specific entry says, else for good. Ignored for the host's store.

When to collect a private store's garbage (it waits until nobody is using the store). Unset: as a less specific entry says, else never. Ignored for the host's store.

When, as 5 cron fields.

The time zone of cron.

Substitute from the host's store: what any repo using it built or fetched, so private stores don't build it all again. Unset: as a less specific entry says, else off.

Users who may read (fetch, browse, logs).

Which Nix store the repo's evaluations, builds and effects use: host, the host's /nix/store, shared with every repo using it; match, on a pattern, one private store for all the repos it matches; repo, a private store of the repo's own. Others' CI can't read a private store, and its paths are served by a binary cache of its own (<cache URL>/store/<name>/-). Unset: as a less specific entry says, else stores.default.

What a private store substitutes from, in place of the host's nix.conf substituters. cache.nixos.org is defined at the normal priority, so a list set here adds to it; lib.mkForce [ ]: none, nothing to ask but privateStore.substituteFromHost. Each one is more to check for every path. Set apart from store, and resolved for the store's name like privateStore: an entry left at cache.nixos.org alone takes a less specific entry's. Ignored for the host's store.

A file outside the store holding user:password, sent as basic auth to the URL's host. Read by the store manager (root) when it starts the store's daemon.

Keys it signs with, trusted on top of the host's.

The binary cache's URL.

Who can see what (see DESIGN.md, access matrix). Unset: as a less specific pattern says, else private.

effect -> token name -> sha256:<hex> (see gtd keys token).

Users who may do anything: push (forced too), delete, decide approvals, and for a pattern, create matching repos by pushing.

Drop logs older than this many seconds.

Protect logs of tags and of commits within keep-1 steps of branch tips.

Drop the oldest logs once the log DB exceeds this many bytes.

The store of repos no entry sets store for: one of their own, or the host's /nix/store, shared (one cache for everything, so nothing is built twice, but anyone whose CI runs there can read what's in it).

A private store's daemon nobody used for this long is stopped.

Private stores' daemons running at once; work for another store waits its turn.

Users. Names are shared by SSH, the web and the cache.

Tokens (their sha256:<hex> hashes, from gtd keys token) for the authenticated binary cache and artifact downloads: the basic-auth password, with the user's name as the user. They carry the user's access: caches and artifacts of the repos they can read.

The hash itself, from gtd passwd. It ends up readable to everyone on the host: prefer passwordHashFile.

A file (outside the store) holding the hash of the user's web password, from gtd passwd. Without a password a user can't log in on the web (SSH keys still work).

Public keys the user logs in with over SSH (git as git@<host>).

Log in to a host through the browser, and make it the active login.

Opens the host's page to authorize gt (log in there first if need be), which hands gt a token for this machine. Where the browser can't reach this machine, --no-browser shows a link to open anywhere and asks for the code it gives.

The logins, which is active, and whether each still works

Who a login is and where, and its token (default: the active one)

Log out: revoke the login's token on its host and forget it

Make a login the active one

Let git use gt's login for HTTPS remotes on its host (in this repo, or for all of yours with --global)

Follow the CI run of a ref live, drawn as on the web.

Until nothing runs any more (or for good, with --follow); follows the ref to new commits. Exits non-zero when the run failed.

A job: what it is, how it went, and its log (live while it runs)

Approve an approval step, after showing what it's about

Deny an approval step (what follows it is skipped)

Run a failed job again (where that makes sense: the latest of it)

Run a scheduled or webhook effect now, on the branch

The repos you can see, with how CI went at their HEAD

Search code, commits and changes (in this repo, or everywhere with --global)

The artifacts of a ref, or one artifact's files

Download an artifact's file (its only file if there's one)

Call the JSON API: GET, or POST with a JSON body. Prints JSON.

The path is under /-/api/ (me, repos, repos/<repo>/refs, …) unless it starts with /.

Follow the host's change events, one JSON object a line

Open the repo (or a ref of it) in the browser; outside a repo, the index