Ci/finix compat matrix

.github/workflows/finix-compat.yml

@@ -0,0 +1,110 @@
+name: finix compatibility
+
+# runs the suite in tests/ against finix *main*, not the pin in lon.lock, and
+# records the result in COMPATIBILITY.md. that is what makes the table's answer
+# - "the last finix commit this module worked with" - move on its own.
+#
+# module failures are recorded, not fatal: this repository says up front that
+# its modules may be minimally maintained and may break. `nix flake check` in
+# ci.yml is the gate that does go red, and it runs against the pinned finix.
+
+on:
+  push:
+    # the table is committed by this workflow; without this it would retrigger
+    # itself forever, since every run stamps a new timestamp into it.
+    paths-ignore:
+      - COMPATIBILITY.md
+      - ci/compat-state.json
+  pull_request:
+  # finix moves whether or not anything lands here, so re-check daily
+  schedule:
+    - cron: "17 5 * * *"
+  workflow_dispatch:
+
+concurrency:
+  group: finix-compat-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+
+jobs:
+  compat:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # the table is committed back on main, and pushing from a shallow
+          # clone after a rebase is rejected
+          fetch-depth: 0
+
+      - name: Make /dev/kvm usable
+        run: |
+          echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' \
+            | sudo tee /etc/udev/rules.d/99-kvm4all.rules
+          sudo udevadm control --reload-rules
+          sudo udevadm trigger --name-match=kvm
+
+      - uses: DeterminateSystems/nix-installer-action@main
+        with:
+          extra-conf: |
+            extra-experimental-features = pipe-operators
+            system-features = nixos-test benchmark big-parallel kvm
+
+      - name: Check out finix main
+        id: finix
+        run: |
+          git clone --depth 1 https://github.com/finix-community/finix .ci/finix
+          echo "rev=$(git -C .ci/finix rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+          echo "date=$(git -C .ci/finix log -1 --format=%cs)" >> "$GITHUB_OUTPUT"
+
+      - name: Run the suite
+        run: FINIX="$PWD/.ci/finix" ci/run-suite.sh
+
+      - name: Render the table
+        run: |
+          args=(
+            --arg finix ./.ci/finix
+            --arg manifest ./.ci/run/manifest.json
+            --arg results ./.ci/run/results.json
+            --argstr rev "${{ steps.finix.outputs.rev }}"
+            --argstr revDate "${{ steps.finix.outputs.date }}"
+            --argstr checkedAt "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+          )
+          # absent on the very first run
+          if [ -f ci/compat-state.json ]; then
+            args+=(--arg state ./ci/compat-state.json)
+          fi
+
+          nix-build ci/report.nix "${args[@]}" -o .ci/report
+          # -m 644: store paths are read-only, and copying the mode along would
+          # make the next run unable to overwrite them
+          install -m 644 .ci/report/compat-state.json ci/compat-state.json
+          install -m 644 .ci/report/COMPATIBILITY.md COMPATIBILITY.md
+
+          cat COMPATIBILITY.md >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload logs
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: finix-compat-logs
+          path: .ci/run/logs
+          retention-days: 14
+
+      - name: Commit the table
+        if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add COMPATIBILITY.md ci/compat-state.json
+
+          if git diff --cached --quiet; then
+            echo "table unchanged"
+            exit 0
+          fi
+
+          git commit -m "ci: update finix compatibility table [skip ci]"
+          git pull --rebase --autostash origin main
+          git push

.gitignore

@@ -0,0 +1,6 @@
+# scratch space for the compatibility suite: the finix checkout it ran
+# against, raw results and logs. the state it keeps lives in ci/.
+/.ci/
+
+result
+result-*

COMPATIBILITY.md

@@ -0,0 +1,53 @@
+# module compatibility
+
+<!-- generated by ci/report.nix - run `ci/run-suite.sh`, do not edit by hand -->
+
+`finix` moves fast and the modules here are minimally maintained by design,
+so this table records, per module, the last `finix` commit it was known to
+work with. a module row that lags behind the commit at the top of this file
+has fallen behind and needs a look.
+
+- last checked against finix [`78fd549`](https://github.com/finix-community/finix/commit/78fd549fa5410ad1e5683efbba2d0f1728c12f3d) (2026-08-23)
+- on `x86_64-linux`, at 2026-08-25T14:44:52Z
+
+| module | checked | status | last finix commit it worked with | that commit |
+| --- | --- | --- | --- | --- |
+| `amnezia-vpn` | eval | working | [`78fd549`](https://github.com/finix-community/finix/commit/78fd549fa5410ad1e5683efbba2d0f1728c12f3d) | 2026-08-23 |
+| `bootchart` | eval | working | [`78fd549`](https://github.com/finix-community/finix/commit/78fd549fa5410ad1e5683efbba2d0f1728c12f3d) | 2026-08-23 |
+| `cups` | eval | working | [`78fd549`](https://github.com/finix-community/finix/commit/78fd549fa5410ad1e5683efbba2d0f1728c12f3d) | 2026-08-23 |
+| `dinit` | eval | working | [`78fd549`](https://github.com/finix-community/finix/commit/78fd549fa5410ad1e5683efbba2d0f1728c12f3d) | 2026-08-23 |
+| `fastfetch` | eval | working | [`78fd549`](https://github.com/finix-community/finix/commit/78fd549fa5410ad1e5683efbba2d0f1728c12f3d) | 2026-08-23 |
+| `gamescope` | eval | working | [`78fd549`](https://github.com/finix-community/finix/commit/78fd549fa5410ad1e5683efbba2d0f1728c12f3d) | 2026-08-23 |
+| `home-manager` | eval | working | [`78fd549`](https://github.com/finix-community/finix/commit/78fd549fa5410ad1e5683efbba2d0f1728c12f3d) | 2026-08-23 |
+| `laptop` | eval | working | [`78fd549`](https://github.com/finix-community/finix/commit/78fd549fa5410ad1e5683efbba2d0f1728c12f3d) | 2026-08-23 |
+| `minimal` | eval | working | [`78fd549`](https://github.com/finix-community/finix/commit/78fd549fa5410ad1e5683efbba2d0f1728c12f3d) | 2026-08-23 |
+| `nix-ld` | eval | working | [`78fd549`](https://github.com/finix-community/finix/commit/78fd549fa5410ad1e5683efbba2d0f1728c12f3d) | 2026-08-23 |
+| `openrgb` | eval | working | [`78fd549`](https://github.com/finix-community/finix/commit/78fd549fa5410ad1e5683efbba2d0f1728c12f3d) | 2026-08-23 |
+| `pipewire` | eval | working | [`78fd549`](https://github.com/finix-community/finix/commit/78fd549fa5410ad1e5683efbba2d0f1728c12f3d) | 2026-08-23 |
+| `preservation` | eval | working | [`78fd549`](https://github.com/finix-community/finix/commit/78fd549fa5410ad1e5683efbba2d0f1728c12f3d) | 2026-08-23 |
+| `river` | eval | working | [`78fd549`](https://github.com/finix-community/finix/commit/78fd549fa5410ad1e5683efbba2d0f1728c12f3d) | 2026-08-23 |
+| `soteria` | eval | working | [`78fd549`](https://github.com/finix-community/finix/commit/78fd549fa5410ad1e5683efbba2d0f1728c12f3d) | 2026-08-23 |
+| `steam` | eval | working | [`78fd549`](https://github.com/finix-community/finix/commit/78fd549fa5410ad1e5683efbba2d0f1728c12f3d) | 2026-08-23 |
+| `tailscale` | eval | working | [`78fd549`](https://github.com/finix-community/finix/commit/78fd549fa5410ad1e5683efbba2d0f1728c12f3d) | 2026-08-23 |
+| `v2rayn` | eval | working | [`78fd549`](https://github.com/finix-community/finix/commit/78fd549fa5410ad1e5683efbba2d0f1728c12f3d) | 2026-08-23 |
+| `xinetd` | eval | working | [`78fd549`](https://github.com/finix-community/finix/commit/78fd549fa5410ad1e5683efbba2d0f1728c12f3d) | 2026-08-23 |
+| `yarr` | eval | working | [`78fd549`](https://github.com/finix-community/finix/commit/78fd549fa5410ad1e5683efbba2d0f1728c12f3d) | 2026-08-23 |
+
+`checked` says how far the suite got with a module. `eval` builds a finix
+system with the module enabled and instantiates its closure, which catches
+the option and api drift that breaks these modules in practice. `eval + vm`
+also boots that system under qemu and asserts the module does its job.
+
+## what is not booted, and why
+
+- `amnezia-vpn` (eval - gui client started by hand from a desktop session; there is nothing to assert on a headless vm)
+- `dinit` (system-services - system-level dinit services; finit is pid 1 on finix, so nothing supervises them - the user half is booted in tests/user-services.nix)
+- `gamescope` (eval - a compositor needs a gpu and a seat; the test vm has neither)
+- `laptop` (eval - an opinionated hardware profile - firmware, backlight, power management; what it does only shows up on a real laptop)
+- `openrgb` (eval - drives rgb controllers over i2c/smbus, none of which a vm has)
+- `pipewire` (eval - needs a sound device and a logged-in seat to reach a running graph)
+- `preservation` (eval - acts from the initrd against a persistent volume; the test vm boots on a tmpfs root with no second volume to preserve to)
+- `river` (eval - a wayland compositor needs a gpu and a seat; the test vm has neither)
+- `soteria` (eval - polkit agent for a graphical session; a headless vm has no session to authenticate for)
+- `steam` (eval - pulls the 32-bit graphics stack and wants a gpu; far too large to boot in ci)
+- `v2rayn` (eval - gui client started by hand from a desktop session; there is nothing to assert on a headless vm)

README.md

@@ -23,6 +23,11 @@ this repository prioritizes:
 - ecosystem growth
 - low contribution friction
 
+because of that, [COMPATIBILITY.md](COMPATIBILITY.md) records, per module, the
+last `finix` commit it was known to work with. it is regenerated on every push
+and daily against `finix` `main`. check it before reaching for a module, and
+see [tests/README.md](tests/README.md) to add a test for one.
+
 # usage (flake-based)
 
 to use this repository, add the following to your flake inputs: