Hooks

Hooks are shell scripts that execute at specific stages during a Job. They allow you to run custom logic before or after Terraform/OpenTofu operations.

Hook Types

Each stage has a before and after hook:

For example, apply_before_hook runs before the apply step, and apply_after_hook runs after.

Inheritance

Hooks can be defined at two levels:

• Namespace: Set default hooks using the default_ prefix (e.g., default_apply_before_hook). These apply to all Modules in the Namespace.
• Module: Override namespace defaults by setting hooks directly (e.g., apply_before_hook).

See the Namespace and Module specifications for full details.

Hook Pre-approval

For security-sensitive environments, Runner Instances can be configured to only execute pre-approved hooks. When enabled, every hook must match (by SHA256 hash) a file in the pre-approved hooks directory.

Configuration

On the Runner Instance, set the following in appsettings.json:

{
  "HooksPreapproval": {
    "Enabled": true,
    "PreapprovedHooksDirectory": "/path/to/approved-hooks"
  }
}

How It Works

1. Place approved hook scripts as files in the PreapprovedHooksDirectory
2. The Runner loads and hashes all files in this directory at startup
3. When a Job runs, each hook is validated against the pre-approved hashes
4. If a hook doesn’t match any pre-approved hash, the Job fails

This ensures that only vetted scripts can execute on your infrastructure, preventing arbitrary code execution from the control plane.

Note: Empty hooks are always allowed. Line endings are normalized before hashing, so the same script will match regardless of platform.