Repository Setup

Hercules CI is configured "by convention" using .nix files in your repository. Follow these steps to ensure a correct setup.

  1. Clone your repository

  2. Write a Nix file. Hercules CI will look for flake.nix, nix/ci.nix, ci.nix or default.nix in the root of the repository.

    The reference has a chapter about evaluation.

  3. Use pinned dependencies instead of <nixpkgs> or similar.

    Hercules CI uses an empty NIX_PATH to help with evaluation reproducibility.

    The unofficial NixOS wiki has a basic method of pinning Nixpkgs.

    You can use an impure evaluation-time fetcher such as builtins.fetchTarball. Note that this makes your evaluation unreproducible if the URL’s resource is mutable.

  4. Optionally, test locally with nix-instantiate

    The behavior of nix-instantiate serves as a reference for evaluation in Hercules CI. You may use the following command to test locally:

    $ NIX_PATH="" nix-instantiate nix/ci.nix

    This may produce a lot of output if you are using import from derivation. You may run it twice for clarity.

  5. Commit and push

  6. Check the attributes via the GitHub commit status or the dashboard. If necessary, see