now-runner 0.1.0

Nix-based distributed command runner
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143

<p align="center">
    <img src="./images/logo.png" alt="now logo" /> <br>
</p>

---

# now

Nix-based distributed command runner.

## Status

Still an early work-in-progress. Expect breaking changes and broken functionality.

## Quick start

```bash
nix run github:EpicEric/now -- init
```

This creates a `now.nix` file in the current directory. To run it:

```bash
nix run github:EpicEric/now -- run now.nix
# --- or ---
nix run github:EpicEric/now -- run .
```

For options and examples:

```bash
nix run github:EpicEric/now -- --help
```

## Workflows

Here's a full example of `now`'s features:

```nix
{ runner, lib, ... }:
{
  name = "Optional name for the workflow";
  # Specify default job(s) to run (override with --job or --all-jobs)
  default = [ "job-1" ];
  jobs = {
    # Jobs are a sequence of steps run on a single machine, in parallel with other jobs
    job-1 =
      { pkgs, ... }:
      {
        name = "Optional name for the job";
        steps = [
          {
            name = "Optional name for the step";
            # Script to run in this step
            run = ''
              python3 --version > file
            '';
            # Packages included in the PATH of the script
            path = [
              pkgs.python313
            ];
          }
          (lib.mkIf (false) {
            name = "Skipped job";
          })
          {
            # You can set environment variables for this step (or for the whole job)
            env = {
              FOO = "Hello!";
              # Runtime-specified variable (interpolation allowed)
              BAR = "${runner.vars.BAR} (copy)";
              # Runtime-specified secret (interpolation not allowed)
              BAZ = runner.secrets.BAZ;
            };
            # You can also specify which shell to use
            shell = pkgs.python313;
            run = ''
              import os

              print(os.environ["FOO"])
            '';
            # Teardown always gets run even if the next steps fail
            teardown = ''
              import os

              # Any printed secrets get anonymized
              print(os.environ["BAZ"])
            '';
          }
          # Special step to build and upload the provided derivation to the Nix store of other runners
          (runner.upload "my-derivation" (
            pkgs.writeText "my-derivation.txt" pkgs.stdenv.hostPlatform.system
          ))
        ];
      };

    another-job =
      # Use runner.matrix to specify multiple remote jobs
      runner.matrix
      [
        {
          # Specify the target system(s) of the remote via pkgs
          pkgs = import <nixpkgs> { system = "aarch64-linux"; };
        }
        {
          # Specify the system features of the remote
          requiredSystemFeatures = [ "kvm" ];
        }
        {
          # Specify other optional parameters
          spam = "with eggs";
        }
      ]
      (
        { pkgs, spam ? null, ... }:
        {
          name = "Matrix job (${if spam != null then spam else pkgs.stdenv.hostPlatform.system})";
          # If fail-fast = true (default), the first failing matrix terminates the job
          strategy.fail-fast = false;
          # Establish that this job must run after another
          needs = [ "job-1" ];
          # Downloads the previous upload with the same name into the runner's Nix store
          env.DRV = runner.download "my-derivation";
          steps = [
            # Special step that simply builds the provided derivation
            (runner.build "some-name" pkgs.hello)
            {
              run = "echo $DRV";
            }
          ];
        }
      )
  };
}
```

## Tests

now is tested with itself. At the root of this repo:

```bash
nix run . -- run now.nix
```