Effects

Effects provide a means to perform actions that affect real-world resources in a controlled manner.

This document serves as reference documentation. See also the Effects Introduction and the deployment guides in hercules-ci-effects.

Running effects

Effects run as part of a job, after all its builds have completed successfully and after preceding jobs for the same repository have completed effect execution.

Sandbox type

Currently, effects run only run on Linux containers only, in a transient container. Note that you can deploy to a macOS machine via SSH from a Linux agent using e.g. hercules-ci-effects runNixDarwin.

Paths

This container contains at least the Nix store and /dev, /proc, /sys, each filled as appropriate for a container.

The store and a nix-daemon socket are accessible.

It may further provide /etc/resolv.conf and other files that are required for network access.

An empty directory is created, to serve as the working directory and TMP.

The /bin/sh and /usr/bin/env executables are not provided by the sandbox and should be installed by the effect instead. Effects defined directly or indirectly through hercules-ci-effects mkEffect provide this by default.

Execution

The process started inside the container is the builder, similar to how the Nix sandbox starts the derivation, but in the effects sandbox, the process appears as uid 0 ("root"), allowing it to modify the root filesystem as necessary. This is possible via uid remapping. The process does not gain any real privileges from being uid 0 in the effects sandbox.

Environment

These are the notable environment variables set by the sandbox itself.

IN_HERCULES_CI_EFFECT

Value: true

HERCULES_CI_API_BASE_URL

The apiBaseUrl configuration value.

HERCULES_CI_SECRETS_JSON

A file path pointing to a file with secrets data.

The contents of the file form a dictionary of names (mostly from secretsMap) to secrets, each with a data object.

See Secrets.

HERCULES_CI_PROJECT_ID

The id UUID of the project that created the job that contains the effect.

HERCULES_CI_PROJECT_PATH

A slash separated string containing in order: the site name (typically github), the owner (user or organization) and the repository name.

Example: github/hercules-ci/hercules-ci-agent

Secrets

The secretsMap declares what secrets should be provided to the effect.

The keys of this attribute set correspond to the keys of the file $HERCULES_CI_SECRETS_JSON inside the effect sandbox.

The values of the attribute specify where the secret may be retrieved. Each value can be:

  • A string, indicating a secret to be read from the agent’s secrets.json

    Local secrets are only granted based on the condition.

  • or an attribute set with a type attribute containing:

    "GitToken"

    Retrieve a short-lived token that gives write access to the repository that contains the effect.

    Available since hercules-ci-agent 0.9.8

    The data of this secret contains a string field called token, which can be used for authentication.

    Example secretsMap value:

    secretsMap = {
  git = { type = "GitToken"; };
};

    Example HERCULES_CI_SECRETS_JSON contents in sandbox:

    {
  "git": {
    "data": {
      "token": "osvh58kfy..."
    }
  }
}

    Example hercules-ci-effects readSecretString call:

    readSecretString "git" ".token"

Additionally, an API token is provided in the hercules-ci field of $HERCULES_CI_SECRETS_JSON.

API token

The hercules-ci secret is provided, containing a token string attribute in its data. This token can be used with the Hercules CI API and has appropriate permissions for the effect’s execution.

This is picked up automatically by the hci command and hercules-ci-effects bash functions like getStateFile.

Network

Network access is provided via the container runtime used.

The current implementation is based on crun and bind mounts /etc/resolv.conf. If your host setup demands a different approach, please open an issue describing your needs or contact mailto:[email protected] if you are hesitant to share any network information.