Nix Integration Guide

ADR Ledger is deeply integrated with the Nix ecosystem, providing reproducible environments and declarative infrastructure enforcement.

Flake Inputs

To use the ledger in your own flake-based project:

{
  inputs.adr-ledger.url = "github:marcosfpina/adr-ledger";

  outputs = { self, adr-ledger, nixpkgs }: {
    # Use ledger components here
  };
}

NixOS Modules

The project provides several modules in nix/modules/:

services.adr-ledger

Enables the core ledger synchronization service and provides the adr CLI to the system path.

services.adr-ledger = {
  enable = true;
  autoSync = true; # runs adr sync on changes
  dataPath = "/var/lib/adr-ledger";
};

adr-ledger-iam

Manages agent users and permissions based on the .governance/governance.yaml definitions.

Library Functions (lib)

The ledger exports a lib attribute containing useful Nix functions for processing ADR data:

• loadKnowledgeBase path: Loads and parses knowledge_base.json.
• filterByProject kb project: Returns ADRs associated with a specific project tag.
• getComplianceTags kb: Extracts all unique compliance tags (e.g., LGPD, SOC2).

Declarative Enforcement (NEUTRON)

A common pattern is to use the ledger to fail builds if compliance rules aren't met:

{ adr-ledger, config, ... }:
let
  kb = adr-ledger.lib.loadKnowledgeBase "${adr-ledger}/knowledge/knowledge_base.json";
  encryptionRequired = builtins.any (adr: adr.id == "ADR-0005") kb;
in {
  assertions = [
    {
      assertion = encryptionRequired -> config.services.disk-encryption.enable;
      message = "ADR-0005 requires disk encryption to be enabled!";
    }
  ];
}

Development Shell

Running nix develop in the project root provides: - Python 3.13 with all necessary dependencies. - The adr operational CLI. - Automatically installed Git hooks. - OPA (Open Policy Agent) for policy validation.

---

See flake.nix for full implementation details.