nixos/docs/flake-lock-automation.md

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:

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.