Document minimal Nixery package requirements for GitHub Actions compatibility

[rkoster]

Summary

When using custom Nixery images with deskrun's cached-privileged-kubernetes runner mode, certain packages must be included in the Nixery image for GitHub Actions to function properly.

Minimal Required Packages

The following packages are needed for basic GitHub Actions functionality (checkout, scripts, etc.):

nixery.dev/shell/bash/findutils/coreutils/gnutar/gnugrep/gzip

Package Breakdown

1. shell - Basic shell environment
2. bash - Bash shell (many actions expect bash)
3. findutils - Provides find command (used by actions/checkout and other actions)
4. coreutils - Basic utilities like ls, mkdir, rm, cat, tail, etc.
5. gnutar - Tar utility (used for artifact handling and checkout)
6. gnugrep - Grep utility (used by various actions)
7. gzip - Compression utility (required by tar for .tar.gz extraction)

Discovery Process

We discovered these requirements iteratively by using a minimal Nixery image and observing failures:

1. Started with nixery.dev/shell/bash - failed with "find: command not found"
2. Added findutils - failed with "gzip: Cannot exec: No such file or directory"
3. Added gzip - checkout succeeded

The other packages (coreutils, gnutar, gnugrep) were included proactively based on common GitHub Actions requirements.

Context

This was discovered while implementing a bootstrap pattern that:

• Uses a minimal Nixery image as the job container
• Mounts the host's nix store at /nix/store
• Finds and uses nix-env from the host store to install additional tools (devbox, docker)
• Avoids the issue where mounting host store over Nixery's /nix/store breaks Nixery package symlinks

Recommendation

Consider documenting this minimal package set in the deskrun documentation, particularly for users who want to:

• Optimize container image size
• Use custom Nixery images
• Bootstrap environments from host nix store

Related

• Issue/PR in instant-cf: Optimize CI build performance using deskrun pattern with host nix/docker cache instant-cf#25
• This pattern enables using host nix store cache while keeping container image minimal