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. Choose which Nix file to use for CI

    Reuse /default.nix

    For simple projects that only need to build for a single architecture and a single set of dependencies.

    or create a /ci.nix or /nix/ci.nix

    For projects that need to build for multiple architectures or versions, or where default.nix already has a special meaning that conflicts with the need for CI.

  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.fetchUrl, although this typically makes your evaluation unreproducible.

  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