hooks

hooks runs commands, sets environment variables, creates gates, and opens OIDC sessions before (pre-hooks) and after (post-hooks) the workflow steps of a Stategraph Orchestration operation. Each hook runs one time per operation. Commands run from the repository checkout directory $TERRATEAM_ROOT.

Default Configuration

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

Keys

In each list, the hooks run in the order that you define them.

Hook Types

env

The env hook type sets environment variables for the operation. It sets one variable from the output of a command, or it sources a script.

Command

Source Method

run

The run hook type runs a command. Orchestration records the output of the command, with secrets masked as ***.

gates

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

drift_create_issue

The drift_create_issue hook type creates an issue in the repository when a drift detection run finds drift. It works only as a plan post-hook of a drift run, and does nothing in other runs. It runs whether the workflow succeeds or fails.

On GitLab, the hook needs an access token in the TERRATEAM_DRIFT_ACCESS_TOKEN CI/CD variable. See drift issues.

oidc

The oidc hook type (type: oidc) opens an OIDC connection to a cloud provider.

Examples

Setting Environment Variables

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

This pre-hook of the plan operation sets TF_VAR_example to example_value.

Running Scripts

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

This post-hook of the apply operation runs cleanup_script.sh, whether the operation succeeds or fails (run_on: always).

AWS OIDC Authentication

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

This pre-hook of all operations opens an OIDC connection to AWS with the role ARN 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 of all operations opens an OIDC connection to GCP with the service account and workload identity provider 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 of all operations opens an OIDC connection to Azure with the client ID, tenant ID, and subscription ID in the matching environment variables.

Creating an Issue on Drift

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

When a drift detection run finds changes, this post-hook of the plan operation creates one issue per directory and workspace with drift.

Considerations

• Hooks can add much time to your operations, for example with long-running commands or scripts.
• Hooks can change files in the repository checkout directory ($TERRATEAM_ROOT). Test your hooks, so that they do not change or delete important files.
• The command or script of a run hook must be available and executable on the runner. Use absolute paths, or install the dependencies.
• The output of a run hook can show sensitive information in the pull request comment when the command fails. Sanitize or mask sensitive data in the output.
• Values that an env hook sets can show in the logs, and other hooks and workflow steps can read them. Do not put sensitive values directly in the hook configuration. Use GitHub secrets, GitLab CI/CD variables, or another secure method.

Related

• workflows
• Custom commands
• Cloud credentials
• Gatekeeper