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"