Effect Core Options

The modularEffect function is a module system-based wrapper for mkEffect.

This page documents the options which are always available. You may add additional options using the module imports syntax.

effectDerivation

The final representation of the effect.

Type

package

effectDerivationArgs

The arguments to the mkEffect function, producing effectDerivation.

Generally you won’t have to set these, as they are represented by other options, with the added benefit of accurate types and support for the merging of definitions.

Type

lazy attribute set of unspecified value

effectScript

Bash statements that form the essence of the effect.

Type

string

Default

""

env

The initial environment variables to set in the effect sandbox.

Type

unspecified value

getStateScript

Bash statements for retrieving deployment state ahead of a deployment.

Stateless deployments do not need this.

Type

strings concatenated with "\n"

Default

""

inputs

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

Type

list of package

Default

[ ]

name

Optional. Allows customization of the name of the effect derivation produced.

Generally the attribute name where the effect is put is more relevant.

Type

null or string

Default

null

putStateScript

Bash statements for saving the deployment state after a deployment.

These will also be run when the effectScript fails.

Type

strings concatenated with "\n"

Default

""

secretsMap

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

The attribute values are converted by retrieving their values and passed to the effect as the JSON file in $HERCULES_CI_SECRETS_JSON.

Type

lazy attribute set of (string or (submodule))

Default

{ }

Example

{
  # simple string means look up in secrets.json on the agent
  "ssh" = "default-ssh";
  # GitToken secrets are provided by Hercules CI backend
  "git" = { type = "GitToken"; };
}

src

A source to be unpacked by the stdenv unpack hook, like mkDerivation would.

Type

null or path

Default

null

Example

''
  lib.cleanSourceWith { path = ./.; filter = path: type: f path type; }
''

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.

Type

strings concatenated with "\n"

Default

""