ready for runners

nixos/secrets/HOWTO.md

@@ -0,0 +1,59 @@
+### 🔧 Using Secrets in NixOS Configurations
+
+You can use decrypted SOPS secrets in your `configuration.nix`, service modules, and flake-based setups.
+
+#### 🔑 1. Use as environment variable (e.g. password)
+
+```nix
+systemd.services.my-service.serviceConfig.EnvironmentFile =
+  config.sops.secrets."my-password".path;
+```
+
+> Your `secrets.yaml` should contain:
+>
+> ```yaml
+> my-password: PASSWORD=supersecret
+> ```
+
+---
+
+#### 🗂 2. Use as file source (e.g. private key or token)
+
+```nix
+environment.etc."ssh/id_ed25519".source =
+  config.sops.secrets."ssh-private-key".path;
+```
+
+> This places the decrypted secret at `/etc/ssh/id_ed25519` with appropriate permissions.
+
+---
+
+#### 👤 3. Read a secret value directly (not recommended for sensitive data)
+
+```nix
+# Use a secret as a string value in a setting
+services.myapp.settings.apiKey = builtins.readFile config.sops.secrets."api-key".path;
+```
+
+---
+
+#### 🛠 4. Use in systemd preStart scripts
+
+```nix
+systemd.services.my-service.preStart = ''
+  export PASSWORD=$(<${config.sops.secrets."my-password".path})
+  ./myapp --auth $PASSWORD
+'';
+```
+
+---
+
+#### 🧠 5. Use in Forgejo user creation
+
+```nix
+systemd.services.forgejo.preStart = ''
+  ${lib.getExe cfg.package} admin user create \
+    --username admin \
+    --password "$(tr -d '\n' < ${config.sops.secrets."admin-password".path})"
+'';
+```