# 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.