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 `true`.
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.`
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`.

`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 or gcp.
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.

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.

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.