Hooks are used to customize the core Terraform and OpenTofu workflow in Scalr. It is a common requirement to run a command, script, or API call before or after the Terraform plan and/or apply events. For example, many customers run lint tests before the plan to ensure the Terraform code is formatted correctly or install software before the apply if it is needed for the Terraform code to execute correctly.

Hooks can be stored in Scalr.io's hooks registry and workspace, or directly on the agent. If your workspaces or runs do not have access to a VCS provider where a hook is stored, then hooks stored on the agents are a good option.

To view hooks configured in Scalr.io and passed to runs, refer to the hooks registry documentation.

For hooks that must be stored on the agent due to constraints accessing a VCS provider, please continue with this doc.

Hooks Types

All of the following hook types can be configured in the Scalr Workspace settings and bundled with the agent setup:

• pre-init – Runs before tofu init during plan and apply operations.
• pre-plan – Runs before tofu plan during a plan operation.
• post-plan – Runs after tofu plan during a plan operation, regardless of whether it completed successfully.
• pre-apply – Runs before tofu apply.
• post-apply – Runs after tofu apply during an apply operation, regardless of whether it completed successfully.

Note that pre-init hook is used in both the plan and apply operation.

Agent-level Hooks

Agent-level hooks can be configured independently from workspace hooks and are bundled with the agent setup. These hooks have the highest priority and are executed before any other hooks during the specified run phase.

If agent-level hooks are configured, they will run on all runs that are executed on the agent.

Hook Files Requirements

To ensure the agent can execute hooks, each file must:

• Be placed in the hooks directory under the agent’s data home directory.
• Have a filename that exactly matches the hook type (e.g., pre-plan).
• Have executable permissions.

For example, to configure pre-plan hook, create a file named /var/lib/scalr-agent/hooks/pre-plan and make it executable.

Hook Environment Variables

The following environment variables are propagated to hook scripts:

• SCALR_TERRAFORM_OPERATION – The current Terraform operation (plan or apply).
• SCALR_TERRAFORM_EXIT_CODE – The exit code (0 or 1) of the previous operation. Available only in post-plan and post-apply hooks.
• SCALR_AGENT_ENV – Path to the file containing custom environment variables, which can be injected into the Scalr Run by hook scripts during execution.

Setting Environment Variables

You can use hooks to define environment variables for subsequent OpenTofu/Terraform commands.

Variables can be exported using the export shell statement directly in the hook body, particularly in scenarios where the hook runs without a shell subprocess.

When a hook is injected via a shell script, variables won’t be exported using the export statement. Instead, you can write lines in KEY=value format to the file specified by the $SCALR_AGENT_ENV environment variable. Use newlines to separate multiple variables.

For example, to set the FOO and BAR variables for use during the tofu plan phase, add the following to a pre-plan hook script:

#!/bin/sh
echo FOO=foo >> "$SCALR_AGENT_ENV"
echo BAR=bar >> "$SCALR_AGENT_ENV"

Environment variables set by a hook script in this way are only applicable to the current operation, and are not persisted for later operations. For example, if FOO=bar is set in the pre-plan hook, then FOO=bar will be set during the tofu plan command, but will not be set during tofu apply. To use the variable during the apply phase, write the variable to the $SCALR_AGENT_ENV file again in the pre-apply hook script.

Environment variables set this way apply only to the current operation and are not persisted across Run stages. For instance, if FOO=bar is written in a pre-plan hook, it will be available during tofu plan but not during tofu apply. To reuse it in the apply phase, you must write it again to $SCALR_AGENT_ENV in the pre-apply hook script.