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"