Effect Declaration

Effects are declared by means of a Nix derivation, and just like Nix shells, they are not built normally. Instead, they execute in a special sandbox that can be customized with the following derivation attributes. This page explains how the derivation is interpreted by Hercules CI Agent.

For writing your own effects, it is recommended to use the hercules-ci-effects attribute documentation. The rest of this page is reference documentation for effects interface.

Attributes

Output-related derivation attributes are mostly ignored.

Currently, __structuredAttributes must not be used in effects. It can be used in dependencies of the effect just fine.

`__hci_effect_mounts`

Since hercules-ci-agent 0.10.1

A JSON object where the field names are paths in the sandbox filesystem, and the values are strings that refer to effect mountables configured on the agent.

Example:

{ "/etc/hosts": "hosts" }

`__hci_effect_virtual_uid`

Since hercules-ci-agent 0.10.1

Default: 0.

The user id number presented to the effect process. This does not change the user id of the process on the host system.

Some programs, including Nix, behave differently when run as UID 0. Set this attribute to a non-zero value to avoid that problem.

`__hci_effect_virtual_gid`

Since hercules-ci-agent 0.10.1

Default: 0.

The group id, analogous to __hci_effect_virtual_uid.

`secretsMap`

See (low-level) Secrets or hercules-ci-effects secretsMap option.