Actions

While Nix builds work well for a large variety of CI requirements, they aren't a good fit when you want your CI job to not just build your repo and run your tests, but also to do something to the external world — upload a docker image, trigger a deployment, send an email, etc. Moreover, sometimes a fully isolated Nix build is too much upfront work, and it's easier to use Nix to provide basic tools (such as cargo, npm, pip, etc.) that you then call as usual, without going through the "pure" versions.

For both of those use cases, garnix actions are a great fit. With actions, you can call an arbitrary executable built with Nix in response to certain events. The executable is called with access to the internet.

To use actions, first define an (x86_64-linux) app in your flake:

{
  ...
  outputs = inputs : {
    apps.x86_64-linux.myApp = ...;
  };
}

Then, in your garnix.yaml, add an actions section in the toplevel:

actions:
  - on: push
    run: myApp

This will run the app as soon as there is a push. Other triggers will be added in the future.

Secrets with actions

Often when interacting with the external world, you'll need to identify yourself. Actions provide a way of doing that. As with hosting secrets, actions run with access to a private key. You can get access to the (age) public key corresponding to it with:

curl https://garnix.io/api/keys/<repo_owner>/<repo_name>/actions/<action_name/key.public

You can then use that public key to encrypt your secrets, and have the action decrypt it as needed. The location of the key is made available to your action in the environment variable $GARNIX_ACTION_PRIVATE_KEY_FILE.

Environment

The following environment variables are available to your apps that run on garnix actions:

• GARNIX_CI - this is always set to true to allow differentiating apps running within garnix actions, and locally.
• GARNIX_BRANCH - this is set to the git branch of the push that triggered this action.
• GARNIX_COMMIT_SHA - this is set to the git commit sha of the push that triggered this action.

The default sandbox is a micro VM with Nix installed, your closure mounted and registered with Nix, but not a lot else. For alternatives (in enterprise deployments) see below.

If you want access to your entire git repo in your action, add withRepoContents: true - e.g.:

actions:
  - on: push
    run: myApp
    withRepoContents: true

Tips

• If possible, avoid building Nix things inside an action, and instead have the action directly depend on those things. This allows us to cache dependencies of your actions instead of having to rebuild every time.
• If you'd like to run an action when a particular build or set of builds succeed, you can depend on those builds (by having for example ${myPackage} in a comment inside a Nix string).
• Logs for building the action (not running it) may currently appear in either the action build or in the app build.
• You can use string interpolations with paths in your repo (e.g. "${./docs}") to get only certain files or directories of your repo to be available in the action. This is an easy way to limit the effect of compromises in actions on the confidentiality of your code.

Enterprise deployment and custom sandboxes

In enterprise deployments, where the action-running servers are dedicated to you alone, it's possible to have other sandbox types than our default, micro VM-based one. In particular you can have more shared resources between actions, allowing for example access to the host Nix daemon, access to /dev/kvm for nested virtualization, shared caches (such as language caches, Docker caches, etc.), and more. If interested, reach out to us by email or on Discord/Matrix.*