Continuous Integration on GitHub Actions

This tutorial explains how to set up a basic continuous integration workflow on GitHub Actions using Nix for package building. By building your package with Nix and uploading it to a binary cache, you'll make it easily accessible to users via the nix run command. This process streamlines package distribution and installation.

The workflow builds the default Nix package defined in your flake using the following third-party actions:

• install-nix-action. There are alternatives to this.
• Cachix via cachix-action for Nix binary cache.

Note that there are some alternative hosted services for Nix CI. If the provided setup doesn't satisfy your requirements, you might consider the following options:

• Garnix
• nixbuild.net

Building packages with Nix

1. Initialize the template from the root directory of the project:

   nix flake init github:akirak/flake-templates#meta

2. Adjust the .github/workflows/nix-build.yml file to match your project requirements.

3. Get an authentication token on Cachix and save it as a secret variable CACHIX_AUTH_TOKEN in your project.

Building multiple packages and performing extra checks

Note

The commands described in this section is also contained as comments in nix-build.yml.

By default, the CI workflow nix-build.yml only builds the default package of the flake:

nix build -L

If your flake exposes multiple packages, you can use the following command instead to build all packages for each platform:

nix build ".#packages.$(nix eval --expr builtins.currentSystem --impure --raw).*" -L --option keep-going true

An alternative way is to add the packages to checks and run nix flake check:

nix flake check -L --option keep-going true

keep-going option inverses the default behavior of fail-fast, which is convenient for CI.

Also see the following issue for updates: nix build --all: build all packages in a flake · Issue #7165 · NixOS/nix · GitHub

Running tests

To run tests using a contained environment in Nix, use checkPhase and set doCheck = true. Consult the builder documentation to see if it has any built-in check.

If you'd rather avoid running tests within Nix's sandbox, create a separate workflow instead in addition to the build workflow.

Also consider

• Update the actions automatically by setting up Renovate. This is already included in the template, so you don't need extra steps for configuration.
• The template also ships with a workflow for checking formats using treefmt-nix. It should work out of the box if your flake supports it, but otherwise it will fail. Check out the documentation for details.
• Use nix-fast-build if you are trying to build a flake containing several outputs with shared dependencies.