Import or pin hercules-ci-effects

The Nix community does not yet have a standard method for adding dependencies at the Nix level. Flakes are a good candidate, but as of writing, they require the use of unstable versions of Nix, which is not production-ready.

Flakes with flake-parts

Use the template as follows, or make the changes further below.

nix flake init -t github:hercules-ci/hercules-ci-effects#flake-parts

Add to the flake inputs:

  hercules-ci-effects.url = "github:hercules-ci/hercules-ci-effects";

In your outputs section:

  outputs = inputs@{ self, flake-parts, hercules-ci-effects, ... }:
    flake-parts.mkFlake { inherit inputs; } ({ withSystem, ... }: {
      imports = [
        # Add this
        hercules-ci-effects.flakeModule
      ];

      # flake.effects is added as onPush.default.outputs.
      # For full flexibility, instead use https://flake.parts/options/hercules-ci-effects.html#opt-herculesCI
      flake.effects = { branch, ... }: withSystem "x86_64-linux" (
        { config, hci-effects, pkgs, inputs', ... }:
        {
          deploy = hci-effects.runNixOS {
            # ...
          };
        }
      );
    });

Flake without flake-parts

This is the recommended integration if migrating to flake-parts is not an option. Otherwise follow the steps for migrating an existing flake.

Limitations:

  • Deployment modules can’t set attributes outside the herculesCI flake output attribute.

  • The implementation is more complicated than mkFlake, in case something breaks.

Benefits:

  • You only have to set a single flake output attribute.

  • Make use of high level features like the flake-update and github-pages options.

  • Merge effects into the onPush.default job, so they run after build success.

  • Run checks that are defined by flake-parts modules.

Add to the flake inputs:

hercules-ci-effects.url = "github:hercules-ci/hercules-ci-effects";

Call the arguments to the flake outputs function inputs; add inputs@ or if it has already been named, adapt the steps after. Example:

outputs = inputs@{ nixpkgs, ... }:

Define the herculesCI flake output attribute. Here’s a complete example:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    hercules-ci-effects.url = "github:hercules-ci/hercules-ci-effects";
  };

  outputs = inputs@{ nixpkgs, ... }:
    # This attrset might instead  be `flake-utils.forEachSystem` or similar.
    {
      packages = nixpkgs.lib.genAttrs ["x86_64-linux" "aarch64-linux"] (system: {
        default = nixpkgs.legacyPackages.${system}.nix.doc;
      });
    }
    // {
      herculesCI = inputs.hercules-ci-effects.lib.mkHerculesCI { inherit inputs; } {
        # Values for flake-parts options may be written here, including
        # non-Hercules-CI options, but those will only take affect in CI and the `hci`
        # command.

        # Automatic flake updates
        # hercules-ci.flake-update.enable = true;

        # If your flake already had a `herculesCI` attribute, move it here.
        herculesCI {
          # Set this to the systems you want to be checked in CI.
          ciSystems = [ "x86_64-linux" ... ];
        };

        # Some modules have options in `perSystem`
        perSystem = { system, hci-effects, ... } = {
          # Many flakes call Nixpkgs, to set some `config` or `overlays`.
          # If yours needs that, it's best to reuse your pkgs here. Example:
          # _module.args.pkgs = pkgsFor.${system};
        };
      };
    };
}

Without defining any values in the module (second mkHerculesCI argument), the behavior of Hercules CI will be the same, but mediated by the hercules-ci-effects flake-parts module.

Flakes with overlay

This method is not recommended, because it does not support effect definitions via flake options.

Add to the flake inputs:

  hercules-ci-effects.url = "github:hercules-ci/hercules-ci-effects";

In your outputs section, call Nixpkgs with the overlay:

  outputs = { nixpkgs, hercules-ci-effects, ... }:
    let
      system = /* ... */;  # or however you bring system into scope
      pkgs = import nixpkgs {
        overlays = [
          hercules-ci-effects.overlay
        ];
      };
      inherit (pkgs) hci-effects; # optional
    in {
      # your flake attributes, using `pkgs.hci-effects` or `hci-effects` (optional)
    }

Flakes without overlay

This method is not recommended, because it does not support effect definitions via flake options.

Although overlays are a convenient way to make definitions available to all your expressions, they aren’t necessary for hercules-ci-effects.

Add the input:

  hercules-ci-effects.url = "github:hercules-ci/hercules-ci-effects";

Call hercules-ci-effects:

  outputs = { hercules-ci-effects, ... }:
    let
      pkgs = /* ... */;
      hci-effects = hercules-ci-effects.lib.withPkgs pkgs;
    in {
      # your flake attributes, using `effects`
    }

niv

Niv is a simple tool that maintains references to dependencies in a JSON file and accompanying Nix file.

Add as a source:

niv add hercules-ci/hercules-ci-effects

Add

let
  inherit (import sources.hercules-ci-effects { inherit pkgs; }) effects;
in
  /* ... */

or if you prefer to use the overlay:

let
  sources = import ./sources.nix;
  pkgs = import sources.nixpkgs {
    config = /* ... */;
    overlays = [
      (import (sources.hercules-ci-effects + "/overlay.nix"))
    ];
    system = /* ... */;
  }
in /* use pkgs.effects */

Other methods

Other methods can be used and require expressions similar to those for niv. Just replace sources.hercules-ci-effects by something that returns the contents of the hercules-ci-effects repository.