From 1231af3fdf36a316fa328ec18002ac59ba9ebbef Mon Sep 17 00:00:00 2001
From: Tom Hubrecht <tom.hubrecht@dgnum.eu>
Date: Mon, 11 Nov 2024 21:53:52 +0100
Subject: [PATCH] feat: Update README

---
 README.md | 79 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 78 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index a2765e9..4f71122 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,79 @@
-# nix-actions
+# 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 ).