hooks

The hooks configuration allow you to run commands or set environment variables before (pre-hooks) and after (post-hooks) workflows. Pre and post hooks are only executed a single time during a Terrateam operation. Commands are executed from the repository checkout directory $TERRATEAM_ROOT.

Default Configuration

hooks:
  all:
    pre: []
    post: []
  plan:
    pre: []
    post: []
  apply:
    pre: []
    post: []

Keys

Key	Type	Description
all	Object	Pre and post hooks for all operations.
plan	Object	Pre and post hooks for plan operations.
apply	Object	Pre and post hooks for apply operations.

Hook Types

env

The env hook type allows you to set environment variables that will be available during the Terrateam operation.

Command

Key	Type	Description
name	String	Name of the environment variable.
cmd	List	Command to use to set the environment variable.
trim_trailing_newlines	Boolean	Trim trailing newlines. Default is true.
sensitive	Boolean	Specify if the value of the environment variable is sensitive. It will be masked in all output. Default: false.

Source Method

Key	Type	Description
method	String	Must be set to source.
cmd	List	Command or script to execute that exports environment variables.
sensitive	Boolean	Indicates whether the environment variables modified by the script are sensitive. If true, they will be masked in all output. Default: false.

run

The run hook type executes a command from the directory that Terrateam is operating against.

Key	Type	Description
cmd	List	Command to run.
run_on	String	Run the command depending on the state of the workflow. Options are success, failure, or always. Default is success.
capture_output	Boolean	When set to true, command output is recorded. Secrets are masked with ***. Default is false.
env	Object	Environment variables to set for this execution. Object keys are environment variable names and the value is a string.
ignore_errors	Boolean	Set to true if failure should be ignored. Default is false, except when on_error contains a gate, in which case it is true.
visible_on	String	When the output of the command should be visible in a PR comment or the UI. Options are always, failure, success. Default is failure.
format	String or Object	Controls how captured command output is rendered in PR comments. String values: code (default, fenced code block), raw (rendered as-is), markdown (rendered as markdown). Object form { type: code, lang: <language> } produces a fenced code block with syntax highlighting for <language>.
on_error	List	Actions to take if the command fails. Each entry is an object with a type. The only supported type is gate, which creates a Gatekeeper gate with the keys token, name, all_of, any_of, and any_of_count.

gates

The gates hook type runs a command and creates a Gatekeeper gate for each entry of the gates list in the JSON the command prints to standard output. The hook never fails the operation.

Key	Type	Description
cmd	List	Command to run. Its standard output must be a JSON object of the form {"gates": [ ... ]}. Each gate accepts token, name, all_of, any_of, any_of_count, and add_reviewers.
env	Object	Environment variables to set for this execution. Object keys are environment variable names and the value is a string.
run_on	String	Run the command depending on the state of the workflow. Options are success, failure, or always. Default is success.

drift_create_issue

The drift_create_issue hook type creates an issue in the repository when a drift detection run finds drift. It is only meaningful as a plan post-hook of a drift run; it does nothing in other runs. It runs regardless of the success of the workflow.

Key	Type	Description
group_by	String	all creates one issue that lists every directory and workspace with drift. dirspace creates one issue per directory and workspace. Default is all.

oidc

The oidc hook type can be used to initiate an OIDC connection to a cloud provider.

Key	Type	Provider	Description
oidc	List		Initiate an OIDC connection to a cloud provider.
provider	String		Name of provider: aws, azure, or gcp. Required for azure and gcp; default is aws.
role_arn	String	aws	Specifies the ARN of an IAM role that you want to use. Value can be specified using a GitHub Secret / environment variable.
assume_role_arn	String	aws	Specifies the ARN of an IAM role that you want to assume into. Default is the value of role_arn. Value can be specified using a GitHub Secret / environment variable.
assume_role_enabled	Boolean	aws	Retrieve a set of temporary security credentials from AWS and set the AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN environment variables. Default is true.
audience	String	aws	Specifies the AWS audience name to use. Default is sts.amazonaws.com. Value can be specified using a GitHub Secret / environment variable.
region	String	aws	Specifies the AWS region to use and sets the AWS_REGION environment variable. Default is us-east-1.
session_name	String	aws	Specifies the AWS session name. Default is terrateam.
duration	Integer	aws	Specifies the AWS session duration in seconds. Default is 3600.
service_account	String	gcp	Email address or unique identifier of the Google Cloud service account for which to generate credentials. Value can be specified using a GitHub Secret / environment variable.
workload_identity_provider	String	gcp	The full identifier of the Workload Identity Provider, including the project number, pool name, and provider name. Value can be specified using a GitHub Secret / environment variable.
access_token_lifetime	Integer	gcp	Desired lifetime duration of the access token, in seconds. Default is 3600.
audience	String	gcp	Specifies the GCP audience name to use. Default is https://iam.googleapis.com/ + workload_identity_provider.
access_token_subject	String	gcp	Email address of a user to impersonate for Domain-Wide Delegation. Value can be specified using a GitHub Secret / environment variable.
client_id	String	azure	App Registration client ID. Value can be specified using a GitHub Secret / environment variable.
tenant_id	String	azure	Azure AD (Entra ID) tenant ID. Value can be specified using a GitHub Secret / environment variable.
subscription_id	String	azure	Default Azure subscription ID. Value can be specified using a GitHub Secret / environment variable.
audience	String	azure	Specifies the Azure audience name to use. Default is api://AzureADTokenExchange.

Examples

Setting Environment Variables

You can use the env hook type to set environment variables that will be available during the Terrateam operation.

hooks:
  plan:
    pre:
      - type: env
        name: TF_VAR_example
        cmd: ['echo', 'example_value']

This pre-hook for the plan operation sets the TF_VAR_example environment variable to example_value.

Running Scripts

The run hook type allows you to execute scripts or commands before or after Terrateam operations.

hooks:
  apply:
    post:
      - type: run
        cmd: ['./cleanup_script.sh']
        run_on: always

This post-hook for the apply operation runs the cleanup_script.sh script, regardless of the operation’s success or failure (run_on: always).

AWS OIDC Authentication

hooks:
  all:
    pre:
      - type: oidc
        provider: aws
        role_arn: ${AWS_ROLE_ARN}

This pre-hook for all operations initiates an OIDC connection to AWS using the role ARN specified in the AWS_ROLE_ARN environment variable.

GCP OIDC Authentication

hooks:
  all:
    pre:
      - type: oidc
        provider: gcp
        service_account: ${GCP_SERVICE_ACCOUNT}
        workload_identity_provider: ${GCP_WORKLOAD_IDENTITY_PROVIDER}

This pre-hook for all operations initiates an OIDC connection to GCP using the service account and workload identity provider specified in the GCP_SERVICE_ACCOUNT and GCP_WORKLOAD_IDENTITY_PROVIDER environment variables.

Azure OIDC Authentication

hooks:
  all:
    pre:
      - type: oidc
        provider: azure
        client_id: ${ARM_CLIENT_ID}
        tenant_id: ${ARM_TENANT_ID}
        subscription_id: ${ARM_SUBSCRIPTION_ID}

This pre-hook for all operations initiates an OIDC connection to Azure using the client ID, tenant ID, and subscription ID specified in the corresponding environment variables.

Creating an Issue on Drift

hooks:
  plan:
    post:
      - type: drift_create_issue
        group_by: dirspace

This post-hook for the plan operation creates one issue per directory and workspace with drift when a drift detection run finds changes.

Considerations

When using hooks in your Terrateam configuration, keep the following considerations in mind:

• Hooks are executed in the order they are defined within each section (pre or post) and each operation type (all, plan, or apply).
• Pre-hooks are executed before the corresponding workflow steps, while post-hooks are executed after the workflow steps.
• Hooks can significantly impact the execution time of your Terrateam operations, especially if they involve long-running commands or scripts. Be mindful of the performance implications when configuring hooks.
• Hooks have access to the repository checkout directory ($TERRATEAM_ROOT) and can modify files within that directory. Ensure that your hooks are carefully tested and do not unintentionally modify or delete important files.
• When using the run hook type, make sure that the specified command or script is available and executable within the Terrateam environment. Consider using absolute paths or ensuring that the necessary dependencies are installed.
• Be cautious when using the capture_output option with the run hook type, as it may expose sensitive information in the GitHub pull request comment if the command fails. Ensure that you properly sanitize or mask any sensitive data before enabling this option.
• When setting environment variables using the env hook type, be aware that the values will be visible in the Terrateam logs and may be accessible to other hooks or workflow steps. Avoid storing sensitive information directly in the hook configuration.
• If you need to use sensitive information in your hooks, consider using GitHub Secrets or other secure methods to store and retrieve the values.