Trusted container authorization
Development preview
This page describes a pinned development revision, not a published release. Its package version may still identify the preceding release while the next version is being prepared.
Native Nix jobs use hardware VM isolation by default. Linux operators may explicitly choose a fresh OCI container per whole job with --weak-containerization. This is shared-kernel isolation, not a VM-equivalent boundary. It is an operator choice for trusted code, including dependencies, flake evaluation, checkout helpers and cleanup. There is no automatic fallback from unavailable VM capacity and no persistent uncontainerized runner.
The coordinator, provider and adapter must all opt in. A coordinator in weak mode selects only weak-container offerings. Use separate coordinator instances for public untrusted work and trusted container work. Older coordinators reject the new isolation value; update both ends before enabling it.
Execution authorization
The coordinator additionally requires one or more operator-owned grants:
sh
--weak-containerization \
--weak-containerization-authorization '30617:<repository-owner-hex>:<identifier>=<trusted-signer-hex-or-npub>'A grant is standing permission for that signer to execute arbitrary code from that exact repository, including future revisions and their dependencies. For PRs the signer is the head revision's author, not the maintainer who toggles its ready status. For manual triggers it is the signed request's author; a trusted manual requester can deliberately authorize someone else's revision. Existing service-request, maintainership and manual-trigger checks still apply. A service request alone does not grant weak execution. Grants are checked on admission, restart and before preparing new allocations. Removing a grant does not undo an allocation already delivered; drain or cancel before changing policy.
Restrict PR intake in ngit-grasp with your chosen allowlist/WoT policy as an additional boundary. CI still checks its own explicit signer grants. Merely naming a trusted repository cannot authorize an arbitrary PR submitter. This change does not implement or change ngit-grasp's intake policy.
Secrets are a separate choice
Enable --weak-containerization-allow-secrets on both coordinator and provider to allow otherwise-authorized secrets. The existing provider secret allowlist and per-repository secret grants remain necessary. Ordinary PR secret restrictions remain unchanged; use an authorized manual execution when needed. Neither execution consent nor weaker isolation grants secrets by itself.
Command secrets retain their existing delivery mechanism. Build-step secrets use the same /run/ngit-ci-build-secrets/<name> interface, but inside the single job container without a nested Nix sandbox. They are removed after the build; the whole container is removed after the job. All code in this job is trusted with its granted secrets. Values travel through the private adapter protocol, not container argv, Docker environment configuration, image layers or host mounts.
Linux runtime and image
The adapter uses the Docker CLI against an operator-controlled daemon. It never accepts runtime flags, mounts, image names or sockets from repository code. Build and load the supplied image, then obtain its immutable ID:
sh
nix build .#weak-container-image
docker load -i result
docker image inspect ngit-ci-weak-container:latest --format '{{.Id}}'Run the adapter under a dedicated account with access to that daemon:
sh
ngit-ci-adapter-container --weak-containerization \
--image sha256:<loaded-image-id> --system x86_64-linux \
--socket /run/ngit-ci-container/adapter.sock \
--state-dir /var/lib/ngit-ci-container/jobsThe account's daemon access is a host administration privilege with a rootful Docker daemon. Keep this account separate from coordinator/provider credentials. Jobs receive no daemon socket, host mounts, host namespaces or privileged mode. The image is pinned by local ID with pulling disabled. Each job has its own writable image layer and store; none is reused between jobs. Nix runs in single-user mode without a nested sandbox. The provider preserves this explicit mode for single-pass jobs while still disabling repository-supplied flake configuration and unsafe native evaluation; hardware jobs retain their required Nix sandbox and build-user group. The native guest protocol handles checkout, evaluation, execution, artifact streaming and cancellation.
CPU, memory including swap, and process limits are required. A Docker daemon and host configuration that cannot enforce them is not a supported deployment. Bridge networking permits ordinary outbound traffic, including reachable LAN services: this tier does not implement the VM backend's host/private-network blocking. Writable image layers do not have a portable enforced disk quota; use a dedicated execution filesystem with adequate reserve and monitor it. These are deliberate weaker guarantees, not equivalent hardware qualification.
The coordinator can stay in Compose with --act-runner none; keep the adapter outside that coordinator container, and attach the provider over its private adapter socket. The provider gets --weak-containerization --adapter-socket ... plus its usual identity, coordinator allowlist, relays and cache configuration. Its signing keys must never enter the job image. No KVM is required for this tier.
Rootless daemons and Docker nested inside LXC/DinD require deployment-specific qualification of cgroup limits, image storage, networking and cleanup. A Docker API alone does not establish those guarantees; see the deployment-specific qualification records. Native Docker-in-Docker inside a workflow is not provided by this image.
NixOS
Import nixosModules.adapter-container and nixosModules.nix-provider. Preload the image and configure its immutable ID:
nix
services.ngit-ci-adapter-container = {
enable = true;
weakContainerization = true;
image = "sha256:<loaded-image-id>";
providerUsers = [ "ngit-ci-nix-provider" ];
};
services.ngit-ci-nix-provider = {
# Retain the usual keys, relays, allowedCoordinators and system configuration.
weakContainerization = true;
weakContainerizationAllowSecrets = false; # explicitly true if desired
adapterSocket = "/run/ngit-ci-container/adapter.sock";
adapterService = "ngit-ci-adapter-container.service";
};
services.ngit-ci.coordinators.trusted = {
# Retain normal coordinator/discovery/provider configuration.
nixWorkflows = true;
actRunner = "none";
weakContainerization = true;
weakContainerizationAllowSecrets = false;
weakContainerizationAuthorization = [
"30617:<repository-owner-hex>:<identifier>=<trusted-signer>"
];
};The adapter module enables Docker and grants only its dedicated adapter account Docker access. providerUsers grants access to the adapter socket, not Docker. Keep the provider's ordinary separate-account cache service configuration.
Recovery and qualification
The adapter's sibling .lock file persists its unique container-label identity; retain it with the cleanup records. Separate deployments need separate state volumes. Before upgrading an older socket-path-labelled adapter, drain jobs and verify no old labelled containers remain; the new identity does not adopt them.
Stop admission before changing the image or policy. Normal cancellation drains through the guest protocol; forced cancellation and disconnect remove the job container. Creation uncertainty or failed cleanup retains a per-job record and blocks restart. Inspect Docker's containers bearing the adapter's ngit-ci.adapter label and the names in state-dir; independently verify their removal before clearing records. Do not delete records merely to restart.
Run the real-runtime test after loading the image:
sh
NGIT_CI_TEST_CONTAINER_IMAGE=sha256:<loaded-image-id> \
cargo test --test docker_weak_container -- --ignored --nocaptureIt verifies private stdin delivery, a real Nix derivation build, fresh job filesystems, forced cancellation and confirmed cleanup. It is also selected by test-docker; missing runtime/image prerequisites fail. The lifecycle test passed with rootless Podman 5.8.8 in the Linux coding VM, including the image's cgroup-v2 limit checks. Docker CI loads the same image before its suite. Separate deployment records cover rootful Docker and unprivileged Proxmox LXC; the rootless smoke test does not qualify them. DinD remains unqualified.
Policy and fake-runtime lifecycle tests are ordinary tests, not evidence of kernel isolation. Before calling a deployment qualified, additionally exercise resource exhaustion, cancellation/disconnect, abrupt adapter restart, artifact publication, secret-bearing native workflows and the actual nested/rootless configuration used by that operator.
Adapter options
CLI flags have corresponding .env/environment variables (CLI wins). All variables below start with NGIT_CI_CONTAINER_.
| Flag | Variable suffix | Default |
|---|---|---|
--weak-containerization | WEAK_CONTAINERIZATION | false; required |
--socket | SOCKET | /run/ngit-ci-container/adapter.sock |
--state-dir | STATE_DIR | /var/lib/ngit-ci-container |
--runtime | RUNTIME | docker |
--image | IMAGE | required immutable local sha256 ID |
--system | SYSTEM | required Linux Nix system |
--memory-mib | MEMORY_MIB | 4096 |
--cpus | CPUS | 2 |
--pids | PIDS | 1024 |
--max-jobs | MAX_JOBS | 1 |