Upgrade from v0.1.1
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.
This temporary migration guide maps the Docker, Proxmox LXC and NixOS recipes at the v0.1.1 tag. Those recipes used act; switching to .grasp/nix workflows also introduces a provider and separate discovery worker. Native workflow files are not a drop-in rename of GitHub Actions YAML. See Nix workflows.
For the reasons behind the change, read Why we moved from act to Nix.
Act execution is deprecated but remains supported in this release. Existing act configurations remain available. Act now defaults to disabled; set --act-runner embedded-act (NixOS actRunner = "embedded-act") to retain local act execution during migration. For act-only operation also set --nix-workflows=false (NGIT_CI_NIX_WORKFLOWS=false, NixOS nixWorkflows = false); otherwise native discovery and provider trust are required. Explicit legacy act settings remain accepted; see configuration compatibility. Native isolation flags do not retroactively make legacy act deployments hardware-isolated. You can retain act while migrating repositories incrementally, or run a native-only coordinator with --act-runner none. Do not mount a Docker socket into the coordinator just to make native execution work.
| Existing v0.1.1 setup | Default native route | Explicit trusted-code alternative |
|---|---|---|
| Compose with privileged DinD sidecar | Keep coordinator; attach provider on a Linux/KVM host or suitable VM | Container adapter on an operator-controlled Docker host; existing DinD topology needs separate qualification |
| Compose using host Docker/rootless Podman socket | Keep coordinator; remove its daemon dependency for native-only operation; attach VM provider | Native local Compose recipe; dedicated adapter owns daemon access; rootless runtime needs resource/cleanup qualification |
| Unprivileged Proxmox LXC, with nested Docker or direct binary | Keep coordinator/discovery in LXC; use provider in separate KVM-capable VM or execution host | Native Compose inside unprivileged LXC, qualified on the recorded configuration; remote container provider also works |
| NixOS bare metal with embedded act | NixOS Firecracker deployment; the coordinator module provisions the discovery worker | Prefer the tested Docker recipe or a remote container provider when deliberately choosing weak execution; existing NixOS weak modules remain available without separate deployment qualification |
| NixOS/Linux VM | Local Firecracker when nested KVM works, otherwise remote provider | Tested Docker recipe where its prerequisites hold, or remote container provider |
| NixOS socket-adapter/QEMU deployment | Retain act adapter while adding a native provider; do not assume an act guest is a native guest template | Tested Docker recipe or remote container provider; the act adapter/template cannot execute native jobs |
A Proxmox VM hosting Firecracker needs nested KVM. An LXC coordinator does not; neither does the weak native container tier. Docker nesting and KVM nesting are different requirements. Making an LXC privileged is not our migration route to VM-grade job isolation.
For public/untrusted PRs, keep the default whole-job VM boundary. For private or restricted-intake repositories, operators may deliberately choose weak containerization, authorize repository/signer pairs, and separately permit secrets. If local prerequisites are unsuitable, keep the coordinator and use a separately hosted trusted provider, or stay on the existing act path while deciding whether to continue self-hosting. No migration requires renting a provider.
Supported routes and deliberate exclusions
The NixOS Firecracker route is in operational use, with dated remote acceptance evidence. The Docker and unprivileged LXC records establish their specific trusted-code configurations. None implies that every runtime, filesystem, nested hypervisor or architecture is qualified.
A v0.1.1 DinD or rootless Podman installation is not restored unchanged by converting its workflows to Nix. The migration path is to move execution to a VM provider, or replace that topology with the tested Docker/LXC weak route and its explicit grants. DinD and rootless Compose remain unqualified; the rootless adapter lifecycle smoke test is not acceptance of the whole deployment. No native option restores uncontainerized host execution or silently falls back when KVM is unavailable. A remote provider may be another machine you own.
Hardware-isolated deployments retain the ordinary secret-provider and repository authorization rules; they require no new weak-mode secret opt-in. NixOS weak-container modules remain available but are not the recommended NixOS migration route. Managed-cache improvements are separate from this migration; follow the selected deployment guide's cache configuration.
Migration sequence
- Choose execution isolation and location independently of coordinator location.
- Install the credential-free discovery worker and configure its private socket. The NixOS coordinator module manages this when
nixWorkflows = true. - Install the provider and the matching adapter/image; configure compute trust in both directions. Preserve keys and deduplication state when upgrading.
- For weak containers, explicitly enable the mode at coordinator/provider/adapter and configure the coordinator's repository/signer grants. Restrict PR intake.
- If needed, configure secret-provider trust and per-repository grants; weak execution additionally needs secret consent on both coordinator and provider.
- Port a small workflow, then verify its signed result, artifacts, cleanup and resource limits on the actual deployment. Test denial of an untrusted PR signer.
- Migrate further workflows, keeping each workload active in only one system to avoid duplicate runs. Once no act workflow remains, set
--act-runner none(NGIT_CI_ACT_RUNNER=none, oractRunner = "none"in the NixOS instance). This disables act dispatch; it does not stop an independently configured adapter service. Disable that act adapter separately and retire its guest templates, DinD sidecar or coordinator Docker socket dependency when unused. Preserve a rollback of configuration and state.
The Mac deployment is separate: genuine macOS jobs retain disposable macOS VMs; Linux containers do not provide a macOS execution environment. See Apple Silicon deployment. Container runtime qualification status and required checks are recorded in the weak-container guide.