Nix Config Update

Updating this flake safely

Read this before running just up, just upp, just up-nix, or just override-pkgs, and before deploying the result to any host.

Core rules

1. Update and deploy are two steps. Never fold "bump the lock file" and "switch every host" into one blind action.
2. Validate before touching a host. An update is only a candidate until just test is green and the affected hosts build locally.
3. One reviewable commit per update. The convention here is a flake.lock: Update commit for the bump; a config change gets its own commit or PR.
4. Keep a way back. Anything that reaches a host needs a rollback path: the previous generation, boot mode, just darwin-rollback, or git revert.
5. Security first. An update re-opens the supply chain. Re-audit every input whose revision moved before you deploy it.
6. Pin third-party inputs. A third-party input — not one of the user's own ryan4yin/* repositories — MUST name a version tag or a fixed commit, not a branch. Official channel upstreams that publish no release (nixpkgs' nixos-unstable/master) are the exception. When only a branch carries a needed third-party change, keep the resolved revision in the lock, record why next to the declaration, and re-audit each update.

1. Pre-flight

• git status is clean, and you are on main or a fresh branch for the work. If you are on an unrelated feature branch, stop and ask for the right branch before bumping.
• just test is green before the update, so you have a baseline to compare against.
• Enough disk for the new closures: df -h /nix/store. Broad nixpkgs bumps pull a lot.
• Know what will move and choose the narrowest recipe that does the job.

2. Run the update

After an update, read git diff flake.lock: it lists exactly which inputs moved and by how many commits. Because just up and just upp commit automatically, either use nix flake update <input> while auditing or amend the generated lock commit after the audit so its message records the conclusion.

3. Audit the change

Treat an update as a supply-chain event.

1. From git diff flake.lock, list every input whose locked.rev changed.

2. Find the inputs that contribute modules this repo imports:

   grep -rn "homeModules\.\|nixosModules\.\|darwinModules\." --include='*.nix' .

3. For each of those inputs, read what changed between the old and new revision in the module files we actually import. Look for:

   • restricted nix.settings (substituters, extra-substituters, trusted-public-keys, trusted-users) — at the Home Manager layer these are ignored for an untrusted user and only warn, but at the system layer they are a root-equivalent trust boundary;
   • environment.etc / home.file entries with a mode or user that widens access;
   • system.activationScripts, systemd.services running as root, sudo/polkit rules;
   • lib.mkForce overrides that silently replace existing settings;
   • eval-time network access or import-from-derivation.

4. For nixpkgs-class inputs, skim the lock diff and expect broken packages and eval deprecation warnings (see "Lessons from past updates").

5. Write the audit conclusion into the update commit message. If an automatic recipe already made the commit, amend it only after reviewing the diff; do not push the unaudited commit first.

4. Validate before deploying

Run these before any host is touched:

• just test — fails (non-zero) unless the suite returns true.
• just eval-host <host> — fast, evaluation only.
• just build-host <host> — builds the full system closure and catches broken packages or build failures that eval misses.
• just build-microvm <guest> — same, for a MicroVM guest.
• nix flake check — broader checks when the change touches shared code.

Cover every host you are about to deploy, and prefer building the closure over trusting a green eval.

Preview what the machine you are on will change before it is deployed:

nix store diff-closures /run/current-system '.#nixosConfigurations.<host>.config.system.build.toplevel'

It lists every package whose version or size moves; an empty result means nothing changes. Read it for unexpected removals, major-version jumps, and kernel or systemd changes that need a reboot.