Skip to content

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

.github/workflows/ci.yml
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:

  1. In Tailscale, add the ci tag with autogroup:admin as the owner.
  2. Create an OAuth client with the "Auth Keys" scope for tag:ci and store it as the TS_OAUTH_CLIENT_ID and TS_OAUTH_SECRET secrets.
  3. Add an access control policy so that the local runner node can SSH into the others as the runner user:

    {
      "action": "accept",
      "src": ["tag:ci"],
      "dst": ["tag:ci"],
      "users": ["runner"],
    }
    

    This rule goes in the ssh section of the policy. The accept action is required, as the check action asks for periodic browser authentication that CI can't provide.

.github/workflows/now.yaml
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

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
begin
  echo '#! /usr/bin/env nix'
  echo '#! nix shell git+https://codeberg.org/now-runner/now#now --command /bin/sh'
  echo 'now run format'
end > .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit
r#'#! /usr/bin/env nix
#! nix shell git+https://codeberg.org/now-runner/now#now --command /bin/sh
now run format
'# | save --force .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit
now.nix
{
  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:

tmp=$(mktemp)
echo '{
  default = [ "hello" ];
  jobs.hello = { pkgs, ... }: {
    steps = [
      {
        run = '"''"'
          ${pkgs.hello}/bin/hello
        '"''"';
      }
    ];
  };
}' > "$tmp"
now run -w "$tmp"
rm "$tmp"

You can declare workflows via process substitution:

now run -w (echo '{
  default = [ "hello" ];
  jobs.hello = { pkgs, ... }: {
    steps = [
      {
        run = '"''"'
          ${pkgs.hello}/bin/hello
        '"''"';
      }
    ];
  };
}' | psub)

You can declare workflows with temporary files:

let tmp = mktemp
r#'{
  default = [ "hello" ];
  jobs.hello = { pkgs, ... }: {
    steps = [
      {
        run = ''
          ${pkgs.hello}/bin/hello
        '';
      }
    ];
  };
}
'# | save --force $tmp
now run -w $tmp
rm $tmp

Customizing pkgs

now.nix
{ 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
        '';
      }
    ];
  };
}
now.nix
{ 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
        '';
      }
    ];
  };
}
flake.nix
{
  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

now.nix
{ 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:

now.nix
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

now.nix
{ 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

now.nix
{
  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
          '';
        }
      ];
    };
}