Effects Introduction

Beyond building the software, it is useful to effect change "in the real world". Steps like deployment have characteristics that Nix’s derivations are not intended for. To support tasks like these, Hercules CI provides an Effects feature, which lets you write Nix expressions that specify what to do when the build succeeds.

effect attributes
Dashboard links to a successful derivation and effect run

Reproducible Deployments

Effects are designed to provide an hermetic environment for your deployments. You can think of it as a better nix-shell or nix develop, something between a shell and the Nix build sandbox.

The effects sandbox gives access to:

  • the Nix store, without the restrictions of the Nix build sandbox

  • the network

  • locally configured secrets

  • the Hercules CI state files API

Secrets are configured locally on your agent machines, so you don’t have to entrust us with your cloud credentials.

nix-build Now Optional

Because Effects are written with in the same language as your builds, you can transparently use anything you’ve built in your deployments.

Here’s the crux of a remote hello world with the hercules-ci-effects library.

mkEffect {
  effectScript = ''
    echo "Hello from effect sandbox"
    ${effects.ssh { destination = "some-host"; } ''
      ${pkgs.hello}/bin/hello
    ''}
  '';
}

If you do need to run dynamic builds from within an effect, that also just works. So all tools like NixOps, Colmena, etc, can run in effects.

State and Locking API

The Hercules CI API provides a convenient way to store deployment information. Think of it as a bucket of files for each of your repositories, with the same permissions and a preserved history.

For example, with NixOps 2 (upcoming release), you can safely collaborate on deployments with minimal configuration. The Hercules CI API then serves as a simple alternative to, say, S3 buckets that you would have to bootstrap manually.

You can use state files and locks using the hci command State files can be accessed through the dashboard in your project’s State tab, through the hci state command, or with the API.

Sequential and Concurrent Execution

Effects only run after the whole build was successful and after all preceding jobs' effects have completed, so you don’t have to worry about concurrent mutation of shared resources in any single effect.

If your job has multiple effects, those will run concurrently, but only with those in the same job.

Contention is low, because only the effectful part of your deployment is mutually exclusive.

Current limitations

Continue