Repository files navigation

InstallsNix on GitHub Actions runners for Linux and macOS.

• Quick installation (~4s on Linux / ~20s on macOS)
• Multi-user installation with sandboxing enabled by default on Linux
• Support forself-hosted GitHub runners
• Allows specifying Nix installation URL viainstall_url (the oldest supported Nix version is 2.3.5)
• Allows specifying extra Nix configuration options viaextra_nix_config
• Allows specifying$NIX_PATH and channels vianix_path
• Enables KVM on supported machines: run VMs and NixOS tests with full hardware-acceleration
• Pair with a binary cache fromcachix-action to speed up re-builds and share binaries across your team

Create.github/workflows/test.yml in your repo with the following contents:

name:"Test"on:pull_request:push:jobs:tests:runs-on:ubuntu-lateststeps:    -uses:actions/checkout@v5    -uses:cachix/install-nix-action@v31with:nix_path:nixpkgs=channel:nixos-unstable    -run:nix-build

name:"Test"on:pull_request:push:jobs:tests:runs-on:ubuntu-lateststeps:    -uses:actions/checkout@v5    -uses:cachix/install-nix-action@v31with:github_access_token:${{ secrets.GITHUB_TOKEN }}    -run:nix build    -run:nix flake check

Some settings have been optimised for use in CI environments:

• nix.conf settings. Override these defaults withextra_nix_config:

  • The experimentalflakes andnix-command features are enabled. Disable by overridingexperimental-features inextra_nix_config.

  • max-jobs is set toauto.

  • show-trace is set totrue.

  • $USER is added totrusted-users.

  • $GITHUB_TOKEN is added toaccess_tokens if no othergithub_access_token is provided.

  • always-allow-substitutes is set totrue.

  • ssl-cert-file is set to/etc/ssl/cert.pem on macOS.

• KVM is enabled on Linux if available. Disable by settingenable_kvm: false.

• $TMPDIR is set to$RUNNER_TEMP if empty.

-name:Print nixpkgs versionrun:nix-instantiate --eval -E '(import <nixpkgs> {}).lib.version'

This action doesn't set up any channels by default.Usenix_path to configure optional channels bypicking a channel orpinning nixpkgs to a specific commit.

-uses:cachix/install-nix-action@v31with:nix_path:nixpkgs=channel:nixos-unstable

See also thetutorial on pinning on nix.dev.

-uses:cachix/install-nix-action@v31with:enable_kvm:trueextra_nix_config:"system-features = nixos-test benchmark big-parallel kvm"

nix-env -i mypackage -f '<nixpkgs>'

If the binary cache you want to add is hosted onCachix and you areusingcachix-action, youshould use theirextraPullNames input like this:

-uses:cachix/cachix-action@v31with:name:mycacheauthToken:'${{ secrets.CACHIX_AUTH_TOKEN }}'extraPullNames:nix-community

Otherwise, you can add any binary cache to nix.conf usinginstall-nix-action's ownextra_nix_config input:

-uses:cachix/install-nix-action@v31with:extra_nix_config:|      trusted-public-keys = hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ= cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=      substituters = https://hydra.iohk.io https://cache.nixos.org/

You can configurejobs.<job_id>.steps[*].shellto usenix develop.

# (optional) pre-build the shell separately to avoid skewing the run time of the next#            step and have clear point of failure should the shell fail to build-name:Pre-build devShellrun:nix build --no-link .#devShells.$(nix eval --impure --raw --expr 'builtins.currentSystem').default-name:Run a command with nix developshell:'nix develop -c bash -e {0}'run:echo "hello, pure world!"

Nix runs commands in a restricted environment by default, calledpure mode.In pure mode, environment variables are not passed through to improve the reproducibility of the shell.

You can use the--keep / -k flag to keep certain environment variables:

-name:Run a command with nix developrun:nix develop --ignore-environment --keep MY_ENV_VAR --command echo $MY_ENV_VARenv:MY_ENV_VAR:"hello world"

Or you can disable pure mode entirely with the--impure flag:

nix develop --impure

In multi-user mode, Nix commands that operate on the Nix store are forwarded to a privileged daemon. This daemon runs in a separate context from your GitHub Actions workflow and cannot access the workflow's environment variables. Consequently, any secrets or credentials defined in your workflow environment will not be available to Nix operations that require store access.

There are two ways to pass AWS credentials to the Nix daemon:

• Configure a default profile using the AWS CLI
• Install Nix in single-user mode

The Nix daemon supports reading AWS credentials from the~/.aws/credentials file.

We can use the AWS CLI to configure a default profile using short-lived credentials fetched using OIDC:

job:build:runs-on:ubuntu-latest# Required permissions to request AWS credentialspermissions:id-token:writecontents:readsteps:      -uses:actions/checkout@v5      -uses:cachix/install-nix-action@v31      -name:Assume AWS Roleuses:aws-actions/configure-aws-credentials@v5.0.0with:aws-region:us-east-1role-to-assume:arn:aws-cn:iam::123456789100:role/my-github-actions-role      -name:Make AWS Credentials accessible to nix-daemonrun:|          sudo -i aws configure set aws_access_key_id "${AWS_ACCESS_KEY_ID}"          sudo -i aws configure set aws_secret_access_key "${AWS_SECRET_ACCESS_KEY}"          sudo -i aws configure set aws_session_token "${AWS_SESSION_TOKEN}"          sudo -i aws configure set region "${AWS_REGION}"

In some environments it may be possible to install Nix in single-user mode by passing the--no-daemon flag to the installer.This mode is normally used on platforms without an init system, like systemd, and in containerized environments with a single user that can own the entire Nix store.

This approach is more generic as it allows passing environment variables directly to Nix, including secrets, proxy settings, and other configuration options.

However, it may not be suitable for all environments.Consult the Nix manual for the latest restrictions and differences between the two modes.

For example, single-user mode is currently supported on hosted Linux GitHub runners, likeubuntu-latest.It is not supported on macOS runners, likemacos-latest.

-uses:cachix/install-nix-action@v31with:install_options:--no-daemon