Botanix

A distributed CI/CD system for Nix projects with webhook integration for Git forges.

Overview

Botanix is coordinator-worker system that builds Nix derivations in response to Git webhooks.

Quick Start

Prerequisites

• Rust (lastest stable)
• Nix with flakes enabled

Start the coordinator (Server)

export WEBHOOK_SECRET='YOUR_WEBHOOK_SECRET'
export FORGEJO_API='https://your-forge.example.com/api/v1/'
export FORGEJO_TOKEN='your_personal_access_token'
cargo run -- --mode server

Start a Worker

First you need a WORKER_TOKEN. You can obtain one by registering with coordinator:

curl -s -X POST YOUR_COORDINATOR_URL:YOUR_PORT/worker/register \
    -H 'Content-Type: application/json' \
    -d '{"systems":[SYSTEM_OF_YOUR_WORKER]}'

Now you can start the worker with the obtained token:

export COORDINATOR_URL='YOUR_COORDINATOR_URL'
export WORKER_TOKEN='YOUR_WORKER_TOKEN_GET_IN_THE_LAST_STEP'
cargo run -- --mode worker

Configure a Webhook

Add a webhook to your Git repository, for now available PROVIDER are { forgejo }

• URL: http://your-server:8080/webhooks/PROVIDER
• SECRET: Same as WEBHOOK_SECRET
• EVENTS: Push events, Pull Request events.

Configuration

Server

• Required:

  • WEBHOOK_SECRET: HMAC secret for validating webhooks
  • NIX_SYSTEMS: Comma separated systems this server supports (default: x86_64-linux).

• Optional:

  • FORGEJO_API: Forgejo API base URL for status updates.
  • FORGEJO_TOKEN: Personal Acess Token for Forgejo API.
  • PORT: Coordinator http Port, (default: 8080)
  • GRPC_PORT: Coordinator gRPC Port, (default: 50051)

Worker

• Required:

  • COORDINATOR_URL: Coordinator server base URL
  • WORKER_TOKEN: Authentication token.
  • NIX_SYSTEMS: Comma separated systems this worker supports (default: x86_64-linux).

• Optional:

  • CACHE_URL: Nix binary cache URL for substitutions.
  • CACHE_NETRC_PATH: Path to .netrc file for authenticated cache access.
  • CHECKOUT_DIR: Directory to store git checkouts (default: follows systemd hierarchy).

Checkout Directory configuration

The worker stores cloned git repositories in a checkout directory. By default, this directory is determined in the following order:

Priority order:

1. CHECKOUT_DIR environment variable (if set by the user).
2. $RUNTIME_DIRECTORY/botanix/checkouts (if RUNTIME_DIRECTORY is set, typically by systemd).
3. $TMPDIR/botanix/checkouts (if TMPDIR is set).
4. /tmp/botanix/checkouts (default fallback).