Open-source project
garnix-io/garnix-ci avatar
garnix-io/garnix-ci

Garnix CI: a self-hostable CI service for flake-based Nix repositories

CI and hosting for nix-based, flakified github repos

502 stars53 forksHaskellBSD-3-Clause

At a glance

What is it?
Garnix is a CI service for nixified, flake-based GitHub repos, and garnix-io/garnix-ci is the open source deployment behind it. This review covers what the repository actually ships, how to spin up the full stack in QEMU VMs, and where the documentation stops short.
Who is it for?
Adopt garnix-ci if you want to read or run a working Haskell implementation of a Nix flake CI service, and you are comfortable with nixos-compose, sops and a GitHub app. Do not adopt it if you wanted a drop-in hosted CI for a private repository with documented SLA, rollback or upgrade procedures; the README does not describe those.
Can I use it commercially?
Yes. BSD-3-Clause is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 151 days ago.
What is it written in?
Mainly Haskell, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • garnix-io/garnix-ci502 ★ · +4
Star history
Repository2026-09-212026-11-15
garnix-io/garnix-ci498502

4 Stars in the last 55 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What garnix-ci is, and who the repository is actually for

Garnix is a CI service for nixified, flake-based GitHub repos. The README opens with exactly that sentence and stops there. What the repository adds is the service itself: a Haskell backend, a frontend, a hosting gateway, DNS and SQL directories, a watchdog, and a flake that ties them together. The audience is narrower than the one-line description suggests. This is not a library you add to an existing pipeline. It is a deployment you stand up, and the README's first instruction is to spin up a couple of qemu VMs that provide a full Garnix deployment. That framing tells you who the code is written for: people who already run NixOS, already use flakes, and want to see or operate the machinery rather than consume it as a hosted product. The acknowledgments section notes that git history was erased when the project was open sourced and lists eight contributors by name. That is a real cost for anyone who wants to read commit-level rationale. If you need to know why a particular backend module looks the way it does, the history will not tell you.

How the pieces fit: a flake, a backend, and a frontend on port 3000

The repository layout is the clearest documentation of the architecture. A top-level flake.nix and flake.lock define the build, cabal.project and backend/ hold the Haskell service, frontend/ holds a web client, and hosting-gateway/, dns/, sql/, opensearch/, secrets/ and watchdog/ are separate top-level directories rather than subdirectories of the backend. That separation suggests the hosting path, DNS records, database schema, search indexing and process supervision are treated as distinct deployable concerns, not as one monolith. The justfile confirms the split in practice: the server recipe changes into backend/, exports a set of S3 cache variables pointing at an R2 bucket and region, and then runs cabal run server with a list of --enable flags including DevApi, OpenSearchMocks, StripeMocks and CacheUploadMocks, on ports 8017, 8018 and 8019. Those mock flags matter. A local run is explicitly a mocked run, so a Stripe or OpenSearch behaviour you observe locally is not evidence of production behaviour. The frontend is run separately with npm run dev from frontend/, and the README says to point a browser at localhost:3000. There is also a docs-infrastructure-generate recipe that renders docs/infrastructure.d2 to SVG with d2, which implies an infrastructure diagram exists in the repository but is not reproduced in the README.

Running Garnix locally in QEMU VMs

The README gives one command to bring up a full deployment. It relies on nixos-compose, a separate project under the same GitHub organization.

bash
nix run -L .#examples_spinUpVms

After that, the README says to tap and inspect the composition, which is how you learn the IP address of the server VM.

bash
nixos-compose tap
nixos-compose status

The status output is what you use to find the exampleGarnixServer address and point a browser at the hosted CI. There is also an admin page at /garnix-admin, described as useful for some development tasks. The example files listed in the repository, examples/default.nix and examples/example-multi-server-deployment.nix, are where the composition is defined, so if the spin-up command fails, those are the files to read rather than the README.

Creating a GitHub app and submitting your first build

Garnix will not work without a GitHub app, and the README is explicit that this applies to production and testing alike. The flow starts on the /garnix-admin page, where a 'Submit to GitHub' button creates the app and returns credentials. Those credentials go into secrets/dev.yaml, which is edited through sops.

bash
sops edit secrets/dev.yaml

After writing the credentials, you enable the app on a repository through the GitHub UI. Only then does the build submission make sense. The README's example posts JSON to the API on the server VM, using the garnix-io/comment repository and a specific commit hash.

bash
curl -v \
  -XPOST \
  http://$(nixos-compose ip exampleGarnixServer)/api/build/submit \
  -H 'Content-Type: application/json' \
  -d '{ "owner": "garnix-io", "repo": "comment", "testCommit": "8b2b57d91dd1f4d094bb944a0a0ef65319a5663f" }'

The README says the build then appears under /repo/garnix-io/comment. Note what is not documented: the response body, the meaning of a failed submission, and whether testCommit must be reachable from the default branch. You will be reading HTTP status codes to debug.

The secrets, sops and GitHub app dependency

The single hardest constraint in this repository is that nothing runs without external credentials. A GitHub app is mandatory, and the README does not describe a mock or offline mode for it. The secrets directory is encrypted with sops, and .sops.yaml sits at the top level, which means anyone running the stack needs a key that can decrypt secrets/dev.yaml. That is a deliberate design: no plaintext credentials in the tree, but also no path to a local run for someone who only has the public repository. The justfile reinforces this by wrapping the server command in withSecrets, so the server recipe fails without decryption capability. If you are evaluating Garnix as a product rather than as a codebase, this is where the open source repository stops being useful to you. The README documents how to create an app and where to put the output, but not how to rotate credentials, how to revoke an app, or what happens to in-flight builds when the app is disabled. For a service whose entire job is responding to repository events, that gap is worth weighing before you plan a deployment.

Where garnix-ci is the wrong tool, and what else exists

The wrong-tool cases are concrete. If you want CI for a repository that is not a flake-based Nix project, Garnix has nothing to do here; the README scopes it to nixified, flake-based GitHub repos and the submission API takes an owner, a repo and a commit. If you want a hosted service with a support contract and documented rollback, the repository is not that either. If you want to modify the frontend, the README does give a path: nixos-compose up -v in one terminal, then npm run dev in frontend/, with the browser pointed at localhost:3000. That is a development loop, not a production topology. Hercules CI appears in the related search data as the comparison people reach for. The difference in approach is architectural: Garnix is a service you deploy (VMs, a backend, a hosting gateway, DNS, a database, a watchdog, a search index), while a typical Nix CI setup leans on a hosted runner that evaluates your flake and reports status back to GitHub. Garnix also caches build outputs to an S3-compatible bucket, which the justfile exposes through S3_CACHE_PUBLIC_BUCKET, S3_CACHE_PRIVATE_BUCKET, S3_CACHE_HOST and S3_CACHE_REGION. If you would rather not operate a cache, a database and a search index, the deployment surface here is larger than the problem you are solving.

Maintenance, licence and upgrade cost

The last push to the default branch was on 2026-06-17, and the repository is not archived. The repository has no published GitHub releases, so there is no tagged version to pin to and no changelog to read between commits. That shapes the upgrade story: you follow main, and the flake.lock is the only version pin the repository gives you. The BSD-3-Clause licence permits use and modification with the usual attribution and warranty disclaimer; it says nothing about the hosted service, the GitHub app you create, or the third-party storage you point the S3 cache variables at, and none of those are covered by the repository's licence terms. The justfile's watch recipes, watch-fast and watch, run ghcid against the test suite with --restart on garnix.cabal, which tells you the intended inner loop for backend work is a fast recompile-and-test cycle rather than a full VM rebuild. That is a reasonable developer experience for Haskell, but it assumes a working cabal setup outside the VM. The README does not describe a release process, a migration path for the sql/ directory, or a supported upgrade sequence between versions. Treat any deployment you build from this repository as something you maintain yourself.

Editorial conclusion

Adopt garnix-ci if you want to read or run a working Haskell implementation of a Nix flake CI service, and you are comfortable with nixos-compose, sops and a GitHub app. Do not adopt it if you wanted a drop-in hosted CI for a private repository with documented SLA, rollback or upgrade procedures; the README does not describe those. Before committing, verify that you can complete the /garnix-admin app creation, write the credentials into secrets/dev.yaml, and get a 200 from /api/build/submit with your own owner, repo and testCommit values.

Frequently asked questions

How do I install Garnix CI and run it locally?

The README gives a single command, nix run -L .#examples_spinUpVms, which spins up a couple of qemu VMs providing a full Garnix deployment through nixos-compose. You then use nixos-compose tap and nixos-compose status to find the server address.

Does Garnix CI need a GitHub app to work?

Yes. The README states you will need a GitHub app for Garnix to work, both for production and for testing. You create one from the /garnix-admin page with the 'Submit to GitHub' button and put the returned credentials into secrets/dev.yaml using sops edit.

How do I submit a test build to Garnix CI?

The README shows a POST to /api/build/submit on the server VM with a JSON body containing owner, repo and testCommit. The example uses the garnix-io/comment repository, and the build then appears under /repo/garnix-io/comment.

Can I develop the Garnix frontend without running the whole deployment?

The README describes running nixos-compose up -v in one place and npm run dev from the frontend directory, then pointing a browser at localhost:3000. The backend still runs in a VM in that setup.

Official sources

  1. garnix-io/garnix-ci on GitHub
  2. Issues
  3. License: BSD-3-Clause
  4. README
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/garnix-io-garnix-ci.svg)](https://hysenlabs.com/projects/garnix-io-garnix-ci)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/garnix-io-garnix-ci.svg)](https://hysenlabs.com/projects/garnix-io-garnix-ci)

Was this useful?