mkEffect :: AttrSet → Effect

A framework for writing any effect.

Essential Parameters

…​ — remaining arguments

Any arguments not explicitly listed here are passed through unmodified to pkgs.stdenvNoCC.mkDerivation, where most attributes are added to the process environment. Most stdenv functionality can be used here as well, with the notable exception of not having build outputs.


Bash statements that form the essence of the effect.


Bash statements to set up user configuration files. Unlike the Nix build sandbox, Effects can make use of a home directory.

Various bash functions are available, such as writeSSHKey

When writing an effect function, it’s often a good idea to let the caller extend this with their own script.


A list of packages that are added to PATH. This behaves like nativeBuildInputs in mkDerivation.


An attribute set of strings that select secrets from the agent’s secrets.json. For example

secretsMap = {
  "ssh" = "default-ssh";

reads the default-ssh secret from secrets.json and makes it available to the effect as a secret named ssh.

This does not include all stdenv parameters that are passed through.


Set this to true if your effect does not need a src attribute. Many effects can use prebuilt configurations and therefore don’t require source files of their own.

mkEffect does keep stdenv’s `unpackPhase and patchPhase.


Default: run the preEffectCheck hooks, effectCheckScript and postEffectCheck hooks.

Not meant to be set; use effectCheckScript or add to the hooks.


Bash statement that check the state of any updated resources.

Runs after putStatePhase and preEffectCheck hooks.



Default: run the preEffect hooks, effectScript and postEffect hooks.

Not meant to be set; use effectScript or add to the hooks.


Default: run the preGetState hooks, getStateScript and postGetState hooks.

Not meant for overriding. See xref:param-getStateScript`.


Bash statements to retrieve the state files.

See also putStateScript.


Default: run the preInit hooks, initScript and postInit hooks.

Not meant for overriding. Most setup is better done in userSetupPhase.


Performs very basic setup tasks to make the sandbox match some expectations.

Not meant to be set. See userSetupScript.



Adds attributes to the returned effect. Use this to set the prebuilt attribute that is recognized by runIf

    passthru = {
      prebuilt = myTopLevelConfigDerivation;
    } // (args.passthru or {});


Overrides the default phases:


priorCheckScript can not be used to prevent further execution of the effect.

Default: run the prePriorCheck hooks, priorCheckScript, report the exit status of that script, and run the postPriorCheck hooks.

Execution of the effect is allowed to continue despite a failed priorCheckScript.

Hook execution is as normal.


priorCheckScript can not be used to prevent further execution of the effect.

Default: ""

Bash statements that check the state of existing resources before the effect runs. Effect execution continues regardless of the outcome, in hope that the effect improves the state of the resources.


Default: run the prePutState hooks, putStateScript and postPutState hooks.

Not meant for overriding. See putStateScript.

Runs not only after effectPhase but also after any failure.


Bash statements to store the state files. These will also be run if the script fails, along with the prePutState and postPutState hooks.

See also getStateScript.



Default: run the preUserSetup hooks, userSetupScript and postUserSetup hooks.

Not meant for overriding; use userSetupScript or add to the hooks.


Return value

mkEffect returns an "Effect", which is a derivation-like attribute set that will be run in `hercules-ci-agent’s Effect sandbox instead of Nix’s build sandbox, as explained in the introduction. It can not be used as a dependency of a derivation, because that would undo Nix’s nice properties.

It retains most of the attributes you can expect on a derivation attribute set. Notable attributes are listed below.


Marks this derivation as an effect, rather than a buildable derivation.



A derivation that contains all the configuration that will be applied.

This can be set via passthru.

See also