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.
evalChecksadds a checkeval-<class>-<name>for every configuration innixosConfigurations,darwinConfigurations, andhomeConfigurations. It forces the full evaluation of the configuration without building it, whichnix flake checkalone does not. Further derivations can be added throughevalTargets.<class>.<name>, andevalTargets.<class>.<name>.enable = falseskips one. SettingevalTargets.<class>.<name>.systemexplicitly avoids evaluating the configuration’s pkgs to find it.libdeclaresflake.libas 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
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
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
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
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
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";
};
mkCheckoutLink
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"