Cookbook¶
A collection of common patterns used with now.
Using now's binary cache¶
A cache containing pre-built binaries is available with the following configuration:
extra-substituters = https://cache.eric.dev.br
extra-trusted-public-keys = cache.eric.dev.br-1:szEyq5LCjxDCUHYSRaSFU5HdHmR7QlT+FRG3tB9QtpE=
Additionally, the NIX_CONFIG environment variable gets forwarded to local and remote builders, so you can use the cache in arbitrary jobs:
export NIX_CONFIG='extra-substituters=https://cache.eric.dev.br extra-trusted-public-keys=cache.eric.dev.br-1:szEyq5LCjxDCUHYSRaSFU5HdHmR7QlT+FRG3tB9QtpE='
now run distributed-job --builders 'ssh://remote'
Using in GitHub Actions¶
on:
push:
branches: ["main"]
jobs:
now:
name: Run CI through now
strategy:
fail-fast: false
matrix:
include:
- runner: ubuntu-24.04
system: x86_64-linux
- runner: ubuntu-24.04-arm
system: aarch64-linux
- runner: macos-26
system: aarch64-darwin
runs-on: ${{ matrix.runner }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Install Nix
uses: NixOS/nix-installer-action@62c1943b776c509394b550f3f983adc14e9212d6 # v1.0.0
with:
add-channel: "true"
extra-conf: |
extra-substituters = https://cache.eric.dev.br
extra-trusted-public-keys = cache.eric.dev.br-1:szEyq5LCjxDCUHYSRaSFU5HdHmR7QlT+FRG3tB9QtpE=
- name: Install now
run: nix profile install git+https://codeberg.org/now-runner/now
- name: Code coverage
env:
CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
run: |
now run ci
Follow these steps first:
- In Tailscale, add the
citag withautogroup:adminas the owner. - Create an OAuth client with the "Auth Keys" scope for
tag:ciand store it as theTS_OAUTH_CLIENT_IDandTS_OAUTH_SECRETsecrets. -
Add an access control policy so that the local runner node can SSH into the others as the
runneruser:This rule goes in the
sshsection of the policy. Theacceptaction is required, as thecheckaction asks for periodic browser authentication that CI can't provide.
on: workflow_dispatch
permissions:
contents: read
actions: read
jobs:
worker:
name: Remote runner (${{ matrix.system }})
strategy:
fail-fast: false
matrix:
include:
- system: aarch64-linux
runner: ubuntu-24.04-arm
- system: aarch64-darwin
runner: macos-26
runs-on: ${{ matrix.runner }}
timeout-minutes: 120
steps:
- name: Install Nix
uses: NixOS/nix-installer-action@62c1943b776c509394b550f3f983adc14e9212d6 # v1.0.0
with:
add-channel: "true"
extra-conf: |
trusted-users = root runner
extra-substituters = https://cache.eric.dev.br
extra-trusted-public-keys = cache.eric.dev.br-1:szEyq5LCjxDCUHYSRaSFU5HdHmR7QlT+FRG3tB9QtpE=
- uses: tailscale/github-action@99a8333667fff04fdd6cffb46dfd409f8329a7bf # v4.3.0
with:
oauth-client-id: ${{ secrets.TS_OAUTH_CLIENT_ID }}
oauth-secret: ${{ secrets.TS_OAUTH_SECRET }}
tags: tag:ci
hostname: now-${{ github.run_id }}-${{ matrix.system }}
args: --ssh
use-cache: "true"
- name: Restore system DNS (macOS)
if: runner.os == 'macOS'
run: sudo networksetup -setdnsservers Ethernet Empty
# Tailscale SSH doesn't source login profiles, and its default PATH includes /usr/local/bin.
- name: Expose Nix on PATH for Tailscale SSH
run: |
sudo mkdir -p /usr/local/bin
sudo ln -sf /nix/var/nix/profiles/default/bin/* /usr/local/bin/
- name: Stay alive until the orchestrator finishes
env:
GH_TOKEN: ${{ github.token }}
run: |
while true; do
status=$(gh api "repos/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID/jobs" \
--paginate \
--jq '.jobs[] | select(.name == "Local runner") | .status')
if [ "$status" = completed ]; then
echo "Orchestrator finished, tearing down."
exit 0
fi
sleep 10
done
orchestrator:
name: Local runner
runs-on: ubuntu-latest
timeout-minutes: 120
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Install Nix
uses: NixOS/nix-installer-action@62c1943b776c509394b550f3f983adc14e9212d6 # v1.0.0
with:
add-channel: "true"
extra-conf: |
extra-substituters = https://cache.eric.dev.br
extra-trusted-public-keys = cache.eric.dev.br-1:szEyq5LCjxDCUHYSRaSFU5HdHmR7QlT+FRG3tB9QtpE=
- uses: tailscale/github-action@99a8333667fff04fdd6cffb46dfd409f8329a7bf # v4.3.0
with:
oauth-client-id: ${{ secrets.TS_OAUTH_CLIENT_ID }}
oauth-secret: ${{ secrets.TS_OAUTH_SECRET }}
tags: tag:ci
hostname: now-${{ github.run_id }}-orchestrator
- name: Install now
run: nix profile install git+https://codeberg.org/now-runner/now
- name: Configure SSH
run: |
sudo tee /etc/ssh/ssh_config.d/50-now.conf >/dev/null <<EOF
Host now-*
User runner
StrictHostKeyChecking no
UserKnownHostsFile /dev/null
LogLevel ERROR
EOF
- name: Wait for workers
run: |
for system in aarch64-linux aarch64-darwin; do
host="now-${{ github.run_id }}-$system"
echo "Waiting for $host..."
for i in $(seq 180); do
if ssh -o BatchMode=yes -o ConnectTimeout=5 "runner@$host" true; then break; fi
[ "$i" = 180 ] && { echo "$host never came up"; exit 1; }
sleep 5
done
done
- name: Run now
run: |
RUN=${{ github.run_id }}
BUILDERS="ssh-ng://runner@now-$RUN-aarch64-linux aarch64-linux - 4 1 ; ssh-ng://runner@now-$RUN-aarch64-darwin aarch64-darwin - 4 1"
now run ci --builders "$BUILDERS"
Installing jobs as a pre-commit hook¶
{
install-pre-commit-hook = {
sandbox.enable = true;
steps = [
{
run = ''
cat > .git/hooks/pre-commit <<EOF
#! /usr/bin/env nix
#! nix shell git+https://codeberg.org/now-runner/now#now --command /bin/sh
now run format
EOF
chmod +x .git/hooks/pre-commit
'';
sandbox.writableDirectory = true;
}
];
};
}
Tip
For a lighter alternative also based on Nix, check out nixhooks.
Inline workflows¶
You can declare workflows with temporary files:
You can declare workflows via process substitution:
Customizing pkgs¶
{ lib, runner, ... }:
let
inputs = import ./.tack;
pkgs = import inputs.nixpkgs {
overlays = [ (import inputs.rust-overlay) ];
};
msrv = (lib.importTOML ./Cargo.toml).package.rust-version;
in
{
jobs = {
test.steps = [
{
env.RUST_LOG = "debug";
path = [
pkgs.cargo-nextest
pkgs.rust-bin.beta.latest.default
];
run = ''
cargo nextest run --no-fail-fast
'';
}
];
clippy.steps = [
{
path = [ pkgs.rust-bin.stable.${msrv}.default ];
run = ''
cargo clippy --all-targets --fix --allow-dirty --allow-staged && cargo fmt --all
'';
}
];
};
}
{ lib, runner, ... }:
let
sources = import ./npins;
pkgs = import sources.nixpkgs {
overlays = [ (import sources.rust-overlay) ];
};
msrv = (lib.importTOML ./Cargo.toml).package.rust-version;
in
{
jobs = {
test.steps = [
{
env.RUST_LOG = "debug";
path = [
pkgs.cargo-nextest
pkgs.rust-bin.beta.latest.default
];
run = ''
cargo nextest run --no-fail-fast
'';
}
];
clippy.steps = [
{
path = [ pkgs.rust-bin.stable.${msrv}.default ];
run = ''
cargo clippy --all-targets --fix --allow-dirty --allow-staged && cargo fmt --all
'';
}
];
};
}
{
inputs = {
# ...
now.url = "git+https://codeberg.org/now-runner/now?ref=main";
rust-overlay.url = "github:oxalica/rust-overlay";
};
outputs =
{
nixpkgs,
now,
rust-overlay,
...
}@inputs:
{
# ...
now =
{ runner, ... }:
let
pkgs = import nixpkgs {
overlays = [ rust-overlay.overlays.default ];
};
in
{
jobs = {
test.steps = [
{
env.RUST_LOG = "debug";
path = [
pkgs.cargo-nextest
pkgs.rust-bin.beta.latest.default
];
run = ''
cargo nextest run --no-fail-fast
'';
}
];
clippy.steps = [
{
path = [ pkgs.rust-bin.stable.${msrv}.default ];
run = ''
cargo clippy --all-targets --fix --allow-dirty --allow-staged && cargo fmt --all
'';
}
];
};
};
};
}
Cross-compilation¶
{ runner, ... }:
{
jobs.cross =
runner.matrix
[
{
pkgs = import <nixpkgs> {
hostSystem = "aarch64-linux";
};
}
]
(
{ pkgs, ... }: {
steps = [
{
path = [ pkgs.nix-info pkgs.nix ];
run = "nix-info";
}
];
}
);
}
Steps are cross-compiled to, and run on, aarch64-linux runners (which are specified with the --builders flag).
To also specify the build system's architecture, use import <nixpkgs> { buildSystem = "..."; }.
Watching for changes¶
One way is to combine watch/watchexec/fswatch and bash's trap, for example:
let
# Build `now` itself, so the steps below can run it (see the quick start
# for alternative installation methods)
now = import (builtins.fetchGit {
url = "https://codeberg.org/now-runner/now";
}) { };
in
{
jobs = {
generate-nix-docs = {
# ...
};
generate-cli-docs = {
# ...
};
serve-docs = { pkgs, ... }: {
steps = [
{
path = [
now
pkgs.watchexec
pkgs.zensical
];
run = ''
trap 'kill 0' EXIT
watchexec -w now.nix -w now/types.nix -r now run generate-nix-docs &
watchexec -w now.nix -w src -r now run generate-cli-docs &
zensical serve -f docs/zensical.toml
'';
}
];
};
};
}
Re-usable workflows and steps¶
{ runner, lib, ... }:
# Workflows are attrsets that can be merged
lib.recursiveUpdate
(import ./.now/foo.nix)
{
jobs.my-job =
{ pkgs, ... }:
let
# Assuming `extraSteps = { step1 = args: ...; step2 = args: ...; };`
extraSteps = import (
pkgs.fetchFromCodeberg {
owner = "now-runner";
repo = "now-services";
hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
}
);
in
{
steps = [
(extraSteps.step1 {
# ...
})
(extraSteps.step2 {
# ...
})
];
};
}
Running steps in an FHS-compatible environment¶
{
default = "fhs";
jobs.fhs =
{ pkgs, ... }:
let
fhsEnv =
pkgs.buildFHSEnv {
name = "fhs-bash";
targetPkgs = pkgs: [
pkgs.gtk3
pkgs.openssl
pkgs.stdenv.cc.cc.lib
pkgs.zlib
];
runScript = "bash";
# Required to find the entrypoint of the FHS environment
meta.mainProgram = "fhs-bash";
};
in
{
steps = [
{
shell = fhsEnv;
path = [
pkgs.wget
];
run = ''
wget -o proprietary-binary https://example.com/downloads/latest-linux-amd64
chmod +x proprietary-binary
./proprietary-binary
'';
}
];
};
}