Nix Flake Updater Module

Automated NixOS module for updating flake.lock with build verification, notifications, and optional AI-powered auto-fix.

Overview

This module provides automated, unattended flake.lock updates that:

• Run on a configurable schedule via systemd timers
• Verify builds across multiple systems before committing
• Optionally use a coding agent (pi) to auto-fix build failures
• Create git branches for review workflow
• Send notifications via ntfy
• Support multiple named instances (e.g., daily, biweekly)
• Support dry-run mode for testing

Files

• default.nix - NixOS module definition
• ../../tools/nix-flake-update/ - Update script package (wrapped with dependencies)

Usage

Import the module and configure instances:

{
  imports = [ ../../modules/nix-flake-updater ];

  services.nix-flake-updater = {
    # Bi-weekly full update with auto-fix
    biweekly = {
      enable = true;
      repoPath = "/home/vincent/src/home";
      buildSystems = [ "okinawa" "kyushu" "rhea" "athena" ];
      schedule = "Sun *-*-1..7,15..21 02:00:00";
      ntfyServer = "https://ntfy.sbr.pm";
      user = "vincent";

      autoFix = {
        enable = true;
        command = "pir";
        extraArgs = [ "--model" "claude-opus-4-6" "--no-session" "--no-extensions" "--no-themes" ];
        maxAttempts = 3;
      };
    };

    # Daily update for specific inputs with auto-merge
    daily = {
      enable = true;
      repoPath = "/home/vincent/src/home";
      flakeInputs = [ "chick-group" "chapeau-rouge" ];
      autoMerge = true;
      buildSystems = [ "okinawa" "kyushu" ];
      schedule = "*-*-* 04:00:00";
      user = "vincent";
    };
  };
}

Auto-Fix

When autoFix.enable = true, build failures trigger a coding agent to attempt fixes:

1. Build error stderr is captured (last 200 lines)
2. The agent is invoked in non-interactive mode (-p) with the error context
3. The agent reads AGENTS.md files in the repo for channel-awareness rules
4. If the fix works, it’s committed separately from the flake.lock update
5. A regression check rebuilds all hosts after fixes are applied
6. Up to maxAttempts retries per failing host

Agent Authentication

The default agent command (pir) uses passage for API key retrieval. For headless systemd execution, ensure the password store is accessible without interactive auth, or use autoFix.envFile to source credentials:

autoFix = {
  enable = true;
  envFile = config.age.secrets."vertex-ai-credentials".path;
};

Manual Trigger

# Run the bi-weekly update manually
sudo systemctl start nix-flake-updater-biweekly

# View logs
journalctl -u nix-flake-updater-biweekly -f

# Check timer schedule
systemctl list-timers 'nix-flake-updater-*'

Configuration Options

Core

• enable - Enable this instance
• repoPath - Git repository path
• buildSystems - List of NixOS systems to build for verification
• schedule - Systemd OnCalendar schedule
• flakeInputs - Specific inputs to update (empty = all)
• user - User to run as (needs git push access)

Git

• gitRemote - Remote to push to (default: origin)
• mainBranch - Main branch name (default: main)
• branchPrefix - Prefix for update branches
• autoMerge - Auto-merge to main on success (default: false)

Notifications

• ntfyServer / ntfyTopic - ntfy notification settings
• ntfyTokenFile - Authentication token file
• inboxOrg - Org-mode inbox for TODO entries on failure

Auto-Fix

• autoFix.enable - Enable AI-powered auto-fix
• autoFix.command - Agent command (default: pir)
• autoFix.extraArgs - Extra agent CLI arguments
• autoFix.maxAttempts - Max retries per host (default: 3)
• autoFix.envFile - Source file for API credentials

Other

• dryRun - Don’t push to remote
• randomizedDelaySec - Random delay before start

Architecture

The update script:

1. Creates an isolated git worktree from main
2. Updates flake.lock (all or specific inputs)
3. Builds all specified systems
4. On failure with auto-fix: invokes coding agent → rebuilds → regression check
5. Commits flake.lock update + any fixes (separate commits)
6. Pushes branch (or auto-merges to main)
7. Sends ntfy notification with results
8. Cleans up worktree

Documentation

See:

• /docs/nix-flake-updater-guide.md - Complete implementation guide