nix-actions/README.md

# Integration of [Forgejo](https://forgejo.org/docs/latest/user/actions/)/[Gitea](https://docs.gitea.com/usage/actions/overview)/[GitHub](https://docs.github.com/en/actions/writing-workflows) workflows with [Nix](https://lix.systems/)

## Features

- Provides checked workflow files thanks to [action-validator](https://github.com/mpalmer/action-validator)
- You can use all the power of Nix to declare workflows: `genAttrs`, `readDir`, ...

## Getting started

### npins

1. Add `nix-actions` to your sources:

```bash
npins add git https://git.dgnum.eu/DGNum/nix-actions
```

2. Integrate workflows to `shell.nix`:

```nix
let
    sources = import ./npins;
    workflows = (import sources.nix-actions { }).install {
        src = ./.;

        workflows.build = {
            name = "Build something";
            on = [ "push" ];
            ...
        };
    };
in

with (import sources.nixpkgs { });

mkShell {
    packages = [ ... ];

    inherit (workflows) shellHook;
}
```

### Options

- `src`: the root of the project, required for the workflows checks
- `platform`: one of `forgejo`, `gitea`, or `github`, this will impact the location of the installed workflow files. Defaults  to `forgejo`.
- `removeUnknown`: whether to remove workflow files not created by `nix-actions`. Defaults to `true`.

### Ensuring all workflows are up to date

Simply add a new workflow for this !

```nix
{
  name = "Check workflows";
  on = [
    "pull_request"
    "push"
  ];

  jobs = {
    check_workflows = {
      runs-on = "nix";
      steps = [
        { uses = "actions/checkout@v3"; }
        {
          name = "Check that the workflows are up to date";
          run = "nix-shell --run '[ $(git status --porcelain | wc -l) -eq 0 ]'";
        }
      ];
    };
  };
}
```

## Examples

The main example is used by the DGNum infrastructure, workflows are defined in https://git.dgnum.eu/DGNum/infrastructure/src/branch/main/workflows .
Be aware that the runners used there are a bit funky and already come with Lix installed (c.f. https://git.hubrecht.ovh/hubrecht/nix-modules/src/branch/main/services/forgejo-nix-runners/default.nix ).