Why we moved from act to Nix
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.
TL;DR
Act runs GitHub Actions workflows on your own machines, but compatibility keeps pulling the design back toward GitHub's conventions, APIs and dependency ecosystem. Self-hosting the runner does not, by itself, free the build from that system. Gitea and Forgejo chose to preserve that compatibility through their own act-derived runners. In our judgement, now that coding agents can handle much of the work of migrating workflows, retaining that compatibility is no longer worth the constraints it places on Grasp CI's design.
Our goal is a marketplace of independently operated compute providers serving coordinators, with no central platform controlling participation. Nix is a better foundation for that vision: jobs carry repository-defined environments, and trusted providers can share cached build outputs so useful work on one machine makes other machines more efficient. Retained caches also help builds keep running when upstream repositories or services are offline or blocking access. The provider and cache-sharing building blocks work today; easier participation and a paid marketplace remain future work.
Why act was a useful starting point
Act let our first release execute familiar GitHub Actions workflows without registering a runner with a forge server. Reusing existing actions and build recipes made it easier to get CI working.
We were not alone in choosing that starting point. Gitea Actions uses a modified act library inside its runner. Forgejo continued that lineage and merged its runner and act codebases. These projects show that act can be the basis of a larger CI system.
The question for us was how much of that larger system to build around it.
Jobs need to move between machines
A release may require Linux and macOS builds, followed by publication only when both succeed. That needs more than running a Linux container on a Mac: jobs that use Darwin SDKs and tooling need an appropriate macOS environment.
Act itself supports direct execution on a macOS host. The difficulty was our integration's execution boundary: one act invocation owned the entire workflow, its dependency graph, intermediate outputs and artifact handling. Moving that invocation to another VM did not let the coordinator place individual jobs on different providers or resume one job using results from another invocation.
Forgejo solves this problem. Its server schedules jobs across registered runners, while its modified runner receives the selected job and dependency context. Our July investigation examined this approach: using it would mean adopting or reproducing the server's task, state, authentication and artifact interfaces, as well as maintaining the relevant Actions semantics.
That was possible, but a different foundation suited Grasp CI better. Nix owns the build dependency graph; our workflow format describes boundaries between independently assigned CI jobs. The coordinator owns scheduling and result recovery, and each provider executes a job and signs its result. A workflow can combine Linux and macOS providers, pass explicit artifacts between jobs, and restart a failed job and its dependants without discarding unrelated completed work.
GitLab illustrates another distinction. It still supports macOS runners, including VM-based execution. What it removed in 17.0 was the standalone gitlab-runner exec command. Its runners remain useful parts of GitLab's scheduling system, but that is not the same as an independent execution engine beneath Grasp CI. A self-hosted forge avoids dependence on a vendor's hosted service; it still carries its own server and runner contract.
Independence includes the dependency chain
A self-hosted runner can still depend on GitHub. A workflow may fetch actions from there, and those actions can fetch other actions, scripts or tool releases. Pinning the top-level workflow does not make every service in that chain available during an outage. For example, actions/setup-node documents GitHub-hosted version manifests and tool downloads even when used with a self-hosted GitHub instance.
Mirrors and caches can help: act has an offline mode, and Forgejo allows independently hosted actions. Those are useful mitigations, but retaining the action repository alone does not retain everything its setup scripts might download.
In our act-based deployments, GitHub outages exposed dependencies that were not obvious from the workflow itself. We wanted a model where preparing, retaining and sharing the build environment was a first-class operation, rather than continually rediscovering what a sequence of setup actions downloads.
Nix exposes build definitions and tool dependencies through the repository's root flake, with inputs pinned by flake.lock. CI-specific definitions belong alongside the workflows in .grasp/nix/ and are imported by that flake; shared product definitions stay in their usual locations. Its flake references can name ordinary Git repositories, tarballs or local paths; GitHub is one supported source, not a required service. The same package or command definition can be used locally and in CI.
This is not automatic independence. A github: input still needs GitHub when its source is unavailable locally, and packages can fetch sources from other hosts. Operators must retain or mirror the flake inputs, package sources and build outputs they need, and account for downloads performed by job commands. Nix provides the mechanisms; choosing independent sources and storage remains part of operating the system.
Caching makes contributed compute go further
Nix caching was a central reason to make this change. A disposable worker should not mean throwing away all the useful work it performed.
Nix can transfer a dependency closure between stores and retrieve matching build outputs from operator-selected binary caches. Jobs and projects using the same compatible inputs can reuse those outputs. That is a build-level reuse model, beyond retaining an action checkout, a container image or a directory of files on one runner.
Provider cache sharing makes that benefit extend beyond one operator's machines. Suppose one provider has already built the toolchain and dependencies for a project. Another provider with a matching system and build inputs can fetch those outputs from a cache it trusts, then spend its compute on the work that is still missing. A new job VM does not have to start from an empty build cache, and a different project using the same dependencies can benefit too.
ngit-ci's authenticated provider cache sharing lets operators explicitly approve other providers' cache identities and signing keys. Providers can publish caches for other providers and ordinary Nix clients to consume. Replica lookup can find retained copies when the original provider no longer has an output. This cache infrastructure works independently of the coordinator: contributing useful cached builds can help other providers without assigning them your jobs.
This is part of how contributed compute can go further. Providers can help build a common supply of reusable dependencies instead of each repeating the same expensive work. Job VMs remain disposable while the useful outputs can outlive them.
Sharing retained inputs and outputs also improves resilience. When an upstream repository, tool-download service or original cache is offline, rate-limiting requests or denying access, another trusted cache can supply the objects it already holds. A provider may then continue a build without contacting that upstream service. This depends on retaining the required inputs and outputs: a cache cannot supply missing objects or replace a live service that a job explicitly calls.
Trust and retention still matter. Discovering a cache on a relay does not authorize it, and a cache signature identifies a trusted publisher rather than proving an honest build. Operators choose whose outputs to accept and which copies to retain.
Nix build caching is also distinct from CI-result reuse. One avoids rebuilding a matching derivation; the other preserves evidence from a compatible job run. Publication and deployment effects need an appropriate workflow reuse policy.
Moving workflows with agent assistance
Our original July proposal introduced Nix as an additional workflow format. It already identified cross-machine scheduling, macOS builds and shared binary caches as the goals. After implementing that path, we chose it as the default for v0.2.
Coding agents make this transition more approachable. They can help translate GitHub Actions steps into Nix packages and commands, organize CI-specific definitions under .grasp/nix/, and connect them to the root flake. You can start from a working workflow and ask an agent to preserve its intent rather than learning the whole Nix language before making a first change.
Give the agent the Nix workflow guide, the existing workflow and the repository's build instructions. Ask it to retain job dependencies, artifacts, secrets and publication conditions, and validate the resulting commands locally and in CI. Renaming YAML is not a conversion; the translated workflow still needs review, especially where it deploys or publishes.
Cold builds can be expensive before caches are populated, and Linux and macOS remain different targets. Agent assistance makes migration easier; it does not remove those platform requirements.
Nix also does not make arbitrary code safe or every build reproducible. The execution backend supplies isolation: disposable Firecracker VMs on Linux, macOS VMs on supported Apple Silicon hosts, or an explicitly authorized weaker container tier. See execution isolation for those boundaries. Docker tools can still run inside a job's disposable VM.
For Grasp CI, that trade gives us a clearer division of responsibility and a better foundation for independently operated compute and caches. Start with the Nix workflow guide for the practical format.
Act is deprecated and disabled by default in v0.2, but explicitly enabled act backends remain available during migration. No removal release is set. The migration guide covers existing installations.