mkEffect

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.

effectScript

Bash statements that form the essence of the effect.

userSetupScript

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.

inputs

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

secretsMap

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.

All Effect-related parameters

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

dontUnpack

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.

effectCheckPhase

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

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

effectCheckScript

Bash statement that check the state of any updated resources.

Runs after putStatePhase and preEffectCheck hooks.

effectScript

See essential parameters

effectPhase

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

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

getStatePhase

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

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

getStateScript

Bash statements to retrieve the state files.

See also putStateScript.

initPhase

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

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

initScript

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

Not meant to be set. See userSetupScript.

inputs

See essential parameters

passthru

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

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

phases

Overrides the default phases:

priorCheckPhase

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

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.

putStatePhase

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.

putStateScript

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.

secretsMap

See essential parameters

userSetupPhase

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

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

userSetupScript

See essential parameters

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.

isEffect

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

prebuilt

Optional

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

This can be set via passthru.

See also