Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Flocken

Flocken (German for “flakes”) is a collection of utilities for nix flakes.

Usage

The project supports semantic versioning, so we advise to pin the major version (e.g., v2) to avoid breaking changes.

{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
    flocken = {
      url = "github:mirkolenz/flocken/v2";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };
  outputs = {nixpkgs, flocken, ...}:  {};
}

The builders of flocken.legacyPackages.${system} are also available through flocken.overlays.default, which builds them from your nixpkgs and makes them available to callPackage.

flocken.lib

A collection of utility functions for nix flakes. See the documentation for more details.

flocken.flakeModules

Modules for flake-parts.

  • evalChecks adds a check eval-<class>-<name> for every configuration in nixosConfigurations, darwinConfigurations, and homeConfigurations. It forces the full evaluation of the configuration without building it, which nix flake check alone does not. Further derivations can be added through evalTargets.<class>.<name>, and evalTargets.<class>.<name>.enable = false skips one. Setting evalTargets.<class>.<name>.system explicitly avoids evaluating the configuration’s pkgs to find it.
  • lib declares flake.lib as a lazy attribute set, so several modules can add helpers to it.
flake-parts.lib.mkFlake { inherit inputs; } {
  imports = [
    flocken.flakeModules.evalChecks
    flocken.flakeModules.lib
  ];
}

flocken.legacyPackages.${system}.mkGitHubBinary

Install binaries from the release assets of a GitHub repository. The release is pinned in a JSON file that the update script (passthru.updateScript) refreshes. assets maps each system to one or more asset names, or is a function of the version returning such a mapping. Assets are downloaded through the GitHub API, anonymously by default. Like private fetchFromGitHub, it authenticates when the Nix daemon passes NIX_GITHUB_PRIVATE_USERNAME and NIX_GITHUB_PRIVATE_PASSWORD, e.g. via the setting impure-env of the experimental feature configurable-impure-env.

mkGitHubBinary {
  owner = "astral-sh";
  repo = "uv";
  file = ./release.json;
  binaries = [ "uv" "uvx" ];
  assets = {
    x86_64-linux = "uv-x86_64-unknown-linux-gnu.tar.gz";
    aarch64-darwin = "uv-aarch64-apple-darwin.tar.gz";
  };
}

flocken.legacyPackages.${system}.mkDarwinApp

Install a macOS app bundle to $out/Applications, optionally wrapping an executable inside it as $out/bin/${pname}. Combine it with mkGitHubBinary.override { constructDrv = mkDarwinApp; } to install apps from GitHub releases.

flocken.legacyPackages.${system}.mkDockerManifest

Create a multi-arch image index from Nix-built images and push it to one or more registries. The images can be archives (e.g., dockerTools.buildLayeredImage) or streams (e.g., dockerTools.streamLayeredImage). Streams of dockerTools are run with the host’s Python, so the images of other platforms need no emulation, only their store paths, which a binary cache filled by native builders can provide. All tags and registries share the same digest, which stays the same when a commit with reproducible images is published again. String options may reference environment variables as $VAR or \${VAR} (escaped from Nix interpolation), which are expanded at runtime ($$ for a literal $). Use them for secrets (e.g., "$GITHUB_TOKEN"), as literal values end up in the Nix store.

docker-manifest = mkDockerManifest {
  github.enable = true;
  images = with self.packages; [ x86_64-linux.docker aarch64-linux.docker ];
};

With github.enable, the index is pushed to ghcr.io and annotated with the repository metadata from the payload of the event that triggered the workflow. Events without a payload, such as schedule, lack the description, homepage, and license.

on:
  push:
    branches: [main]
jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: DeterminateSystems/nix-installer-action@v23
      - run: nix run .#docker-manifest
        env:
          VERSION: "1.0.0"
          GITHUB_TOKEN: ${{ github.token }}

GitLab CI/CD

With gitlab.enable, the index is pushed to the project’s container registry and annotated with the project metadata from the predefined variables of GitLab CI/CD. GitLab does not expose the license or homepage of a project without its API, so set these annotations explicitly if needed.

release:
  image: nixos/nix
  script:
    - nix run .#docker-manifest
  variables:
    VERSION: "1.0.0"

Signing with cosign

Set cosign.enable = true to sign the index with cosign. Keyless signing in GitHub Actions additionally requires the id-token: write permission. In GitLab CI/CD, it requires an ID token with the sigstore audience, which is only accepted by the public Sigstore instance for GitLab.com:

release:
  id_tokens:
    SIGSTORE_ID_TOKEN:
      aud: sigstore

The index is pushed untagged to all registries, signed and attested in the first one, and its signatures and attestations are copied to the others, before it is tagged. Signatures can be verified as follows:

cosign verify \
  --certificate-identity https://github.com/OWNER/REPO/.github/workflows/WORKFLOW.yml@refs/heads/main \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  REGISTRY/REPO:TAG

For GitLab, the identity is https://gitlab.com/GROUP/PROJECT//.gitlab-ci.yml@refs/heads/main and the issuer is https://gitlab.com.

SBOMs and provenance

With cosign.enable, an image’s SBOM, a CycloneDX, SPDX 2, or SPDX 3 JSON document, is attested to the manifest of that image’s platform, since each platform has its own dependencies. It is read from the image’s passthru.sbom or given explicitly:

docker-manifest = mkDockerManifest {
  github.enable = true;
  cosign.enable = true;
  images = map (system: {
    image = self.packages.${system}.docker;
    sbom = "${self.packages.${system}.sbom}/sbom.cdx.json";
  }) [ "x86_64-linux" "aarch64-linux" ];
};

The attestation can be verified and downloaded as follows:

cosign verify-attestation --type https://cyclonedx.org/bom \
  --certificate-identity https://github.com/OWNER/REPO/.github/workflows/WORKFLOW.yml@refs/heads/main \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  REGISTRY/REPO@$(regctl image digest --platform linux/amd64 REGISTRY/REPO:TAG) \
  | jq -r .payload | base64 -d | jq .predicate

The name and digest of the index are passed on to later steps or jobs following the conventions of each platform. With github.enable, they are the step outputs name and digest, for example to attest its build provenance:

permissions:
  packages: write
  id-token: write
  attestations: write
steps:
  - run: nix run .#docker-manifest
    id: manifest
    env:
      VERSION: "1.0.0"
      GITHUB_TOKEN: ${{ github.token }}
  - uses: actions/attest-build-provenance@v4
    with:
      subject-name: ${{ steps.manifest.outputs.name }}
      subject-digest: ${{ steps.manifest.outputs.digest }}
      push-to-registry: true

With gitlab.enable, they are written to gitlab.outputFile and become the variables DOCKER_MANIFEST_NAME and DOCKER_MANIFEST_DIGEST of later jobs:

release:
  script:
    - nix run .#docker-manifest
  artifacts:
    reports:
      dotenv: docker-manifest.env
deploy:
  needs: [release]
  script:
    - echo "$DOCKER_MANIFEST_NAME@$DOCKER_MANIFEST_DIGEST"

lib

Utility functions for nix flakes, grouped by topic. All of them are available directly as flocken.lib.<name>, e.g. flocken.lib.getModules.

attrsets

isEmpty

Check if a value of arbitrary type is empty.

Inputs

value
The value to check for emptiness.

Type

isEmpty :: Any -> Bool

Examples

isEmpty ""
=> true
isEmpty null
=> true
isEmpty [ ]
=> true
isEmpty { }
=> true
isEmpty "foo"
=> false
isEmpty [ "foo" ]
=> false
isEmpty { foo = "bar"; }
=> false

isNotEmpty

Check if a value of arbitrary type is non-empty. Opposite of isEmpty.

Inputs

value
The value to check for non-emptiness.

Type

isNotEmpty :: Any -> Bool

Examples

isNotEmpty ""
=> false

maybe

Return the value if the condition is true, otherwise return null.

Inputs

cond
The condition to check.
value
The value to return if the condition is true.

Type

maybe :: Bool -> Any -> Any

Examples

maybe true "foo"
=> "foo"
maybe false "foo"
=> null

isEnabled

Checks if an attrset has a key with the name enable set to true.

Inputs

x
The attrset to check.

Type

isEnabled :: { enable ? Bool } -> Bool

Examples

isEnabled { enable = true; }
=> true
isEnabled { enable = false; }
=> false
isEnabled { }
=> false

getLeaves

Get all leaves of an attrset.

Inputs

attrs
The attrset to get the leaves of.

Type

getLeaves :: AttrSet -> AttrSet

Examples

getLeaves {
  foo = {
    bar = "baz";
  };
}
=> {
  "foo.bar" = "baz";
}

attrByDottedPath

Return an attribute from nested attribute sets.

Inputs

path
The path to the attribute.
default
The default value to return if the attribute does not exist.
set
The attribute set to get the attribute from.

Type

attrByPath :: String -> Any -> AttrSet -> Any

Examples

attrByPath "foo.bar" "default" { foo = { bar = "baz"; }; }
=> "baz"

getAttrFromDottedPath

Like attrByDottedPath, but without a default value. If it doesn’t find the path it will throw an error.

Inputs

path
The path to the attribute.
set
The attribute set to get the attribute from.

Type

getAttrFromDottedPath :: String -> AttrSet -> Any

Examples

getAttrFromDottedPath "foo.bar" { foo = { bar = "baz"; }; }
=> "baz"

setAttrByDottedPath

Create a new attribute set with value set at the nested attribute location specified in PATH.

Inputs

path
The path to the attribute.
value
The value to set.

Type

setAttrByDottedPath :: String -> Any -> AttrSet

Examples

setAttrByDottedPath "foo.bar" "baz"
=> { foo = { bar = "baz"; }; }

configurations

githubSshKeys

Returns a list of GitHub SSH keys for a user.

Inputs

user
The GitHub username to get the SSH keys for.
sha256
The sha256 hash of the file.

Type

githubSshKeys :: { user: String, sha256: String } -> [ String ]

Examples

githubSshKeys {
  user = "mirkolenz";
  sha256 = lib.fakeSha256;
}
=> [
  "ssh-rsa AAAA..."
  "ssh-rsa AAAA..."
]

nixDaemonSocket

Get the path of the nix daemon socket after symlink resolution, e.g. for sandbox profiles. Upstream Nix uses the default socket on every platform. On darwin, Determinate Nix links the default socket to /var/run/nix-daemon.socket, which the /var firmlink resolves to /private/var/run.

Inputs

stdenv
The stdenv of the host platform.
determinate
Whether the host runs Determinate Nix, defaults to false.

Type

nixDaemonSocket :: { stdenv: Stdenv, determinate: Bool } -> String

Examples

nixDaemonSocket { inherit (pkgs) stdenv; }
=> "/nix/var/nix/daemon-socket/socket"
nixDaemonSocket {
  inherit (pkgs) stdenv;
  determinate = true;
}
=> "/private/var/run/nix-daemon.socket" # on darwin

mkMutableFiles

Create a home-manager activation entry that installs writable copies of files after linkGeneration. Useful for programs that rewrite their own config and fail on read-only store symlinks. The declared content is restored on every activation.

Inputs

config
The home-manager configuration.
files
A list of { source, target, mode ? "600" } attrsets.

Type

mkMutableFiles :: { config: AttrSet, files: [ { source: Path, target: String, mode: String } ] } -> DagEntry

Examples

home.activation.zedSettings = mkMutableFiles {
  inherit config;
  files = [
    {
      source = settingsFile;
      target = "${config.xdg.configHome}/zed/settings.json";
    }
  ];
};

mkMutableFile

Like mkMutableFiles, but for a single file.

Inputs

config
The home-manager configuration.
source
The file to copy.
target
The absolute path of the writable copy.
mode
The file mode of the copy, defaults to 600.

Type

mkMutableFile :: { config: AttrSet, source: Path, target: String, mode: String } -> DagEntry

Examples

home.activation.zedSettings = mkMutableFile {
  inherit config;
  source = settingsFile;
  target = "${config.xdg.configHome}/zed/settings.json";
};

Create a home-manager activation entry that links a target to a local checkout, so edits take effect without a rebuild. Unlike config.lib.file.mkOutOfStoreSymlink, hosts without the checkout are skipped instead of getting a dangling link.

Inputs

config
The home-manager configuration.
target
The absolute path of the link.
checkout
The absolute path of the checkout.

Type

mkCheckoutLink :: { config: AttrSet, target: String, checkout: String } -> DagEntry

Examples

home.activation.nvimConfig = mkCheckoutLink {
  inherit config;
  target = "${config.xdg.configHome}/nvim";
  checkout = "${config.home.homeDirectory}/projects/nvim-config";
};

filesystem

getModules

Get all modules in a directory. Can for instance be used to automatically import all modules in a directory. Directories containing a default.nix file are considered modules. Paths starting with _ are ignored.

Inputs

dir
The directory to search for modules in.

Type

getModules :: Path -> [ Path ]

Examples

getModules ./.
=> [
  ./module1
  ./module2
]

optionalPath

Get a path as a list if it exists. Returns an empty list if the path does not exist. Useful for adding optional paths to import statements.

Inputs

path
The path to check for existence.

Type

optionalPath :: Path -> [ Path ]

Examples

optionalPath ./module.nix
=> [ ./module.nix ]
optionalPath ./non-existing-module.nix
=> [ ]

importOverlays

Compose the overlays of a directory in the order of their names, found like getModules does. Each one holds an overlay final: prev: { ... } that sees the preceding ones in its prev, so numeric prefixes such as 10-inputs.nix and 90-hotfixes.nix control the precedence.

Inputs

dir
The directory containing the overlays.

Type

importOverlays :: Path -> Overlay

Examples

import nixpkgs {
  overlays = [ (importOverlays ./overlays) ];
}

packages

disableUpdateScript

Remove the update script of a package, e.g. one inherited from a nixpkgs package that would edit the nixpkgs sources.

Inputs

pkg
The package to remove the update script from.

Type

disableUpdateScript :: Derivation -> Derivation

Examples

disableUpdateScript pkgs.hello
=> «derivation» with passthru.updateScript = null

setUpdateScriptAttrPath

Set the attribute path that nix-update resolves the package at. Naming where a package actually lives keeps nix-update from selecting it through a flattened set, which would force every package of that set just to answer one lookup. Packages without an update script are left unchanged.

Inputs

attrPath
The attribute path of the package, separated by dots.
pkg
The package to set the attribute path for.

Type

setUpdateScriptAttrPath :: String -> Derivation -> Derivation

Examples

setUpdateScriptAttrPath "vimPlugins.foo" pkgs.vimPlugins.foo
=> «derivation» with passthru.updateScript.attrPath = "vimPlugins.foo"

isHydraTarget

Check if CI should build a derivation, following the meta.hydraPlatforms convention of Hydra. Without meta.hydraPlatforms, the derivation is built on its own system.

Inputs

drv
The derivation to check.

Type

isHydraTarget :: Derivation -> Bool

Examples

isHydraTarget pkgs.hello
=> true
isHydraTarget (pkgs.hello.overrideAttrs { meta.hydraPlatforms = [ ]; })
=> false

mkDockerManifest

annotations

Annotations for the manifest, nested attribute sets are flattened to dotted keys. Most org.opencontainers.image annotations are set automatically if the GitHub or GitLab integration is enabled. The created and revision annotations are read from the git repository in the working directory if there is one.

Type: attribute set of anything

Default:

{ }

autoTags

Configuration for tags that are generated automatically.

Type: submodule

Default:

{ }

autoTags.branch

Whether to enable add a tag based on the branch name.

Type: boolean

Default:

true

Example:

false

autoTags.latest

Whether to enable add a ‘latest’ tag if branch == defaultBranch.

Type: boolean

Default:

true

Example:

false

autoTags.major

Whether to enable add a tag based on the major version (e.g., 1).

Type: boolean

Default:

true

Example:

false

autoTags.majorMinor

Whether to enable add a tag based on the major and minor version (e.g., 1.2).

Type: boolean

Default:

true

Example:

false

autoTags.version

Whether to enable add a tag based on the version (e.g., 1.2.3).

Type: boolean

Default:

true

Example:

false

branch

Name of the git branch (e.g., main).

Type: null or string

Default:

"`$GITHUB_REF_NAME` or `$CI_COMMIT_BRANCH` in branch pipelines if the GitHub or GitLab integration is enabled, else the checked out git branch"

compression

Compression of the image layers, null keeps them as they are in the images.

Type: null or one of “gzip”, “zstd”

Default:

"gzip"

cosign

Configuration for signing the manifest with cosign.

Type: submodule

Default:

{ }

cosign.enable

Whether to enable signing the pushed manifest with cosign.

Type: boolean

Default:

false

Example:

true

cosign.extraArgs

Extra arguments passed to cosign sign and cosign attest.

Type: list of string

Default:

[ ]

cosign.key

Path or KMS URI of a cosign key. Null means keyless OIDC signing.

Type: null or string

Default:

null

Example:

"cosign.key"

cosign.recursive

Whether to enable signing each per-platform image in the manifest list.

Type: boolean

Default:

true

Example:

false

defaultBranch

Name of the git branch that is used as default for the latest tag.

Type: null or string

Default:

"the repository's default branch if the GitHub or GitLab integration is enabled, else `main`"

format

The format of the manifest

Type: one of “oci”, “v2s2”

Default:

"oci"

github

GitHub integration configuration

Type: submodule

Default:

{ }

github.enable

Whether the GitHub integration is enabled. If set to true, the repository metadata is read from the GitHub Actions environment and event payload at runtime.

Type: boolean

Default:

false

Example:

true

github.actor

GitHub actor. Used as default value for registries."ghcr.io".username.

Type: string

Default:

"$GITHUB_ACTOR"

github.outputFile

File that the name and digest of the pushed index are appended to as step outputs, skipped if empty.

Type: string

Default:

"$GITHUB_OUTPUT"

github.registry

Name of the GitHub registry

Type: string

Default:

"ghcr.io"

github.repo

Full name of the GitHub repository (e.g., mirkolenz/flocken). Used as default value for registries."ghcr.io".repo.

Type: string

Default:

"$GITHUB_REPOSITORY"

github.token

GitHub access token. Used as default value for registries."ghcr.io".password.

Type: string

Default:

"$GITHUB_TOKEN"

gitlab

GitLab integration configuration

Type: submodule

Default:

{ }

gitlab.enable

Whether the GitLab integration is enabled. If set to true, the project metadata is read from the predefined variables of GitLab CI/CD at runtime.

Type: boolean

Default:

false

Example:

true

gitlab.outputFile

File that the DOCKER_MANIFEST_NAME and DOCKER_MANIFEST_DIGEST of the pushed index are appended to, skipped if empty. Its variables are passed to later jobs if it is declared as artifacts:reports:dotenv.

Type: string

Default:

"docker-manifest.env"

gitlab.password

Password for the GitLab container registry. Used as default value for registries."$CI_REGISTRY".password.

Type: string

Default:

"$CI_REGISTRY_PASSWORD"

gitlab.registry

Name of the GitLab container registry.

Type: string

Default:

"$CI_REGISTRY"

gitlab.repo

Full path of the GitLab project (e.g., mirkolenz/flocken). Used as default value for registries."$CI_REGISTRY".repo.

Type: string

Default:

"$CI_PROJECT_PATH"

gitlab.username

Username for the GitLab container registry. Used as default value for registries."$CI_REGISTRY".username.

Type: string

Default:

"$CI_REGISTRY_USER"

images

Images to be added to the manifest, given as packages or as attribute sets with an image and its sbom. Note: This should be a list of identical images for different architectures.

Type: non-empty (list of ((submodule) or package convertible to it))

Example:

with self.packages; [ x86_64-linux.image aarch64-linux.image ]

images.*.image

Nix-built image, either an archive (e.g., pkgs.dockerTools.buildLayeredImage) or a stream (e.g., pkgs.dockerTools.streamLayeredImage). Streams of pkgs.dockerTools are run with the Python interpreter of the host, so images of other platforms need no emulation.

Type: package

images.*.sbom

SBOM of the image as a CycloneDX, SPDX 2, or SPDX 3 JSON document, whose format is detected from its content. It is attested to the manifest of the image’s platform if cosign.enable is set.

Type: null or absolute path

Default:

image.passthru.sbom or null

Example:

"${self.packages.x86_64-linux.sbom}/sbom.cdx.json"

registries

Configuration for the Docker registries to be used. The key is the name of the registry (e.g., ghcr.io). The index is pushed untagged to all registries, signed and attested in the first one, and its signatures and attestations are copied to the others, before it is tagged.

Type: attribute set of (submodule)

Default:

{ }

registries.<name>.enable

Whether to enable pushing to the registry.

Type: boolean

Default:

true

Example:

false

registries.<name>.name

The name/domain of the registry

Type: string

Default:

"‹name›"

registries.<name>.password

Password for pushing to the registry.

Type: string

registries.<name>.repo

Fully qualified name of the Docker image in the registry (e.g., mirkolenz/flocken).

Type: string

registries.<name>.tls

Whether to use TLS, insecure skips the certificate verification and disabled uses plain HTTP.

Type: one of “enabled”, “insecure”, “disabled”

Default:

"enabled"

registries.<name>.username

Username for pushing to the registry.

Type: string

tags

List of custom/additional tags to be added to the manifest.

Type: list of string

Default:

[ ]

version

Semantic version of the image (e.g., v1.0.0 or 1.0.0).

Type: string

Default:

"$VERSION"