README.md


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

# nix2workflow

![test status](https://github.com/getchoo/nix2workflow/actions/workflows/ci.yaml/badge.svg)
[![FlakeHub](https://img.shields.io/endpoint?url=https://flakehub.com/f/getchoo/nix2workflow/badge)](https://flakehub.com/flake/getchoo/nix2workflow)

nix2workflow is a library for generating github matrices from regular nix flake outputs.

## usage

we offer both a standard library for use in any flake, along with
a [flake-parts](https://flake.parts/) module for easier integration.

you can find an example workflow for use in your own project in
[./.github/workflows/example.yaml](./.github/workflows/example.yaml).

### flake module

a basic setup might look like this. please see the [module](./module.nix)
for all options

```nix
{
  imports = [nix2workflow.flakeModule];

  githubWorkflowGenerator = {
    outputs = [
      "checks"
      "devShells"
      "nixosConfigurations"
      "packages"
    ];

    overrides = {
      checks.systems = ["x86_64-linux"];
    };
  };
}
```

a full example can be found in [./test/module/flake.nix](./test/module/flake.nix)

### library

the regular library will have a more complicated setup, though
it also allows using lower level functions and has no restrictions on
what flake outputs are used.

```nix
{
  githubworkflow = let
    workflow = nix2workflow.lib {inherit self;};
    outputs = [
      "checks"
      "devShells"
      "nixosConfigurations"
      "packages"
    ];
  in {
    matrix.include = lib.concatLists (
      map (
        output:
          workflow.mkMatrix {
            inherit output;
            # you can also specify what systems to build each output for
            systems = ["x86_64-linux" "aarch64-darwin"];
          }
      )
      outputs
    );
  };
}
```

you can see a full example in [./test/lib/flake.nix](./test/lib/flake.nix)

### in workflows

when the matrix is imported, a few variables with added to the `matrix` context.
these can allow you to customize your workflow based on what packages are building -
such as enabling QEMU when building for aarch64

| name | use |
| --- | --- |
| `os` | the operating system of the current output. usually `ubuntu-latest` or `macos-latest` |
| `arch` | the architecture of the current output. will be `aarch64` or `x64` |
| `attr` | the flake attribute of the current output (can really be anything) |

## related projects
  - [nix-community/nix-github-actions](https://github.com/nix-community/nix-github-actions/)
    - this is the primary inspiration for this project - and i believe also one of the first 
    projects to attempt this, so kudos! i just wanted a more opionated and expandable approach :)