Merge pull request #3 from beatz174-bit/codex/implement-flake.lock-automation-in-nixos-26sknf

Add scheduled flake.lock updater and NixOS evaluation workflows (GitHub + Gitea) and docs

.gitea/workflows/check-nixos.yml

@@ -0,0 +1,27 @@
+name: Check NixOS configurations
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  eval-hosts:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install Nix
+        uses: DeterminateSystems/nix-installer-action@v19
+
+      - name: Evaluate all NixOS hosts
+        run: |
+          set -euo pipefail
+          for host in nixos docker kuma server nix-cache nix-minimal; do
+            echo "Evaluating ${host}"
+            nix --extra-experimental-features 'nix-command flakes' eval \
+              ".#nixosConfigurations.${host}.config.system.build.toplevel.drvPath" --raw
+          done

.gitea/workflows/update-flake-lock.yml

@@ -0,0 +1,32 @@
+name: Update flake.lock
+
+on:
+  schedule:
+    - cron: "0 6 * * 1"
+  workflow_dispatch:
+
+jobs:
+  update-flake-lock:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install Nix
+        uses: DeterminateSystems/nix-installer-action@v19
+
+      - name: Update and commit flake.lock
+        run: |
+          set -euo pipefail
+          nix --extra-experimental-features 'nix-command flakes' flake update
+
+          if git diff --quiet -- flake.lock; then
+            echo "No flake.lock changes detected"
+            exit 0
+          fi
+
+          git config user.name "gitea-actions"
+          git config user.email "gitea-actions@nix-cache.local"
+          git add flake.lock
+          git commit -m "chore: update flake.lock"
+          git push

.github/workflows/check-nixos.yml

@@ -0,0 +1,27 @@
+name: Check NixOS configurations
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  eval-hosts:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install Nix
+        uses: DeterminateSystems/nix-installer-action@v19
+
+      - name: Evaluate all NixOS hosts
+        run: |
+          set -euo pipefail
+          for host in nixos docker kuma server nix-cache nix-minimal; do
+            echo "Evaluating ${host}"
+            nix --extra-experimental-features 'nix-command flakes' eval \
+              ".#nixosConfigurations.${host}.config.system.build.toplevel.drvPath" --raw
+          done

.github/workflows/update-flake-lock.yml

@@ -0,0 +1,37 @@
+name: Update flake.lock
+
+on:
+  schedule:
+    - cron: "0 6 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  update-flake-lock:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install Nix
+        uses: DeterminateSystems/nix-installer-action@v19
+
+      - name: Update flake.lock
+        run: |
+          nix --extra-experimental-features 'nix-command flakes' flake update
+
+      - name: Create pull request
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          add-paths: flake.lock
+          branch: chore/update-flake-lock
+          title: "chore: update flake.lock"
+          commit-message: "chore: update flake.lock"
+          body: |
+            This is an automated update of `flake.lock` generated by the scheduled workflow.
+            
+            It updates pinned flake inputs so dependency updates can be reviewed and merged via PR.

docs/flake-lock-automation.md

@@ -0,0 +1,71 @@
+# flake.lock automation
+
+This repository uses CI workflows to keep `flake.lock` up to date on a schedule and to verify that all declared NixOS hosts still evaluate after dependency updates.
+
+## What this automation does
+
+- A scheduled workflow runs `nix flake update` once per week.
+- On GitHub, any resulting `flake.lock` change is proposed through a pull request.
+- On Gitea, the workflow can commit and push `flake.lock` directly when PR automation is not configured.
+- A separate CI workflow evaluates every configured host before merge:
+  - `nixos`
+  - `docker`
+  - `kuma`
+  - `server`
+  - `nix-cache`
+  - `nix-minimal`
+
+## Why hosts should stop using `--upgrade-all`
+
+`flake.lock` is the source of truth for pinned dependency versions in a flake-based workflow. Normal host rebuilds should consume the committed lock file instead of upgrading dependencies ad-hoc on each machine.
+
+Recommended rebuild command:
+
+```bash
+sudo nixos-rebuild switch --flake git+https://gitea.lan.ddnsgeek.com/beatzaplenty/nixos.git#$(hostname)
+```
+
+Using the committed lock file keeps all hosts aligned and makes updates auditable through CI and code review.
+
+## Command differences
+
+- `nix flake update`
+  - Updates flake input pins in `flake.lock`.
+  - Should be run in CI or in a dedicated update PR workflow.
+- `nixos-rebuild --upgrade`
+  - Primarily for channel-based workflows; not the normal path for flake-pinned deployments.
+- `nixos-rebuild --upgrade-all`
+  - Aggressively updates package sources and bypasses coordinated lock-file updates.
+  - Avoid for routine flake-based host rebuilds.
+
+## nix-cache and remote builder fit
+
+With `nix-cache` acting as a binary cache and remote builder, lock-file updates become safer and more reproducible:
+
+- CI verifies host evaluations against the updated lock file.
+- Builds can be performed once on the remote builder.
+- Built artifacts can be served via `nix-cache` to other hosts, reducing rebuild time and drift.
+
+## Token and secret handling
+
+Do **not** commit access tokens into `flake.nix`, `flake.lock`, or any other tracked file.
+
+If private source access is needed:
+
+- configure tokens locally in `~/.config/nix/nix.conf` or equivalent machine-local config, or
+- provide tokens through CI secrets/environment variables.
+
+## GitHub Actions setup notes
+
+- Ensure `GITHUB_TOKEN` has permission to create branches and pull requests (workflow sets `contents: write` and `pull-requests: write`).
+- The update workflow uses `peter-evans/create-pull-request` with branch `chore/update-flake-lock`.
+- The evaluation workflow runs on pull requests, pushes to `main`, and manual dispatch.
+
+## Gitea Actions runner setup notes
+
+- Ensure the runner image includes Git and can execute the Nix installer action.
+- For direct push mode, grant workflow push permission to the repository.
+- The workflow sets commit identity to:
+  - `user.name = gitea-actions`
+  - `user.email = gitea-actions@nix-cache.local`
+- Commits are only created when `flake.lock` actually changes.