Configuration

The Terrateam configuration file (config.yml) is the primary way to customize how Terrateam interacts with your GitHub repository and Terraform code. This file is stored in the .terrateam directory at the root of your repository.

Basic structure

The config.yml file is written in YAML and has the following basic structure:

access_control:
  # Access controls
apply_requirements:
  # Apply requirements
dirs:
  # Repository layout definitions
hooks:
  # Hooks
workflows:
  # Custom workflow steps
# Other configuration options

Access control

Access control allows you to define policies for who can perform various Terrateam operations, such as planning and applying changes. You can configure access based on individual users, GitHub teams, or repository collaborator roles.

Here’s an example access control configuration:

access_control:
  policies:
    - tag_query: ''
      plan: ['*']
      apply: ['team:sre']

This configuration allows anyone to trigger a plan operation but restricts apply operations to members of the sre team.

For more information, see the access control section of the configuration reference.

Apply requirements

Apply requirements allows you to specify conditions that must be met before an apply operation can be performed on an unmerged pull request. This helps ensure that changes are properly reviewed and validated before being applied.

Here’s an example apply requirements configuration:

apply_requirements:
  checks:
    approved:
      enabled: true
      count: 2
    merge_conflicts:
      enabled: true
    status_checks:
      enabled: true
      ignore_matching:
        - "ci/.*"
  create_pending_apply_check: true

This configuration requires that the pull request has at least 2 approvals, no merge conflicts, and all status checks (except those matching ci/.*) have passed before an apply can be performed.

When create_pending_apply_check is enabled, Terrateam will create a GitHub status check for each dirspace that is pending an apply. This prevents the pull request from being merged until all apply operations have completed.

For more information, see the apply requirements section of the configuration reference.

Dirs

Dirs allow you to define which tags, workspaces, and when modified rules rules apply to specific directories in your repository.

Here’s an example directory configuration:

dirs:
  ec2:
    tags: [aws, ec2]
    workspaces:
      production:
        tags: [production]
    when_modified:
      file_patterns: ["ec2/*.tf", "ec2/*.tfvars", "iam/*.tf", "iam/*.tfvars"]
  iam:
    tags: [aws, iam]

This configuration assigns the tags aws and ec2 to the ec2 directory, and the tags aws and iam to the iam directory. It also specifies that the production workspace should be used when a tag query includes aws, ec2, and production for a workflow or command. Additionally, it overrides the when_modified file patterns for the ec2 directory.

Terrateam also supports glob patterns in the dirs directive, allowing you to match multiple directories with similar configurations. The ${DIR} variable can be used to specify the directory that Terrateam is working against, relative to the root of the repository.

For more information, see the dirs section of the configuration reference.

Hooks

Hooks allow you to run custom commands or set environment variables before (pre-hooks) or after (post-hooks) Terrateam operations. There are three types of hooks:

all: Executed for both plan and apply operations
plan: Executed only for plan operations
apply: Executed only for apply operations

Here’s an example hooks configuration:

hooks:
  all:
    pre:
      - type: run
        cmd: ['echo', 'Running pre-hook for all operations']
  plan:
    post:
      - type: run
        cmd: ['echo', 'Running post-hook for plan operations']

For more details, see the hooks section of the configuration reference.

Workflows

Workflows allow you to define custom steps for Terrateam’s plan and apply operations. You can use workflows to replace or augment the default behavior.

Here’s an example workflow configuration:

workflows:
  - tag_query: "dir:production"
    plan:
      - type: init
      - type: plan
        extra_args: ["-var-file=production.tfvars"]
    apply:
      - type: init
      - type: apply

This workflow runs a custom plan and apply process for any changes in the production directory, using a specific tfvars file.

For more information, see the workflows section of the configuration reference.

Other configuration options

The config.yml file supports many other configuration options, including:

default_tf_version: Set the default Terraform version to use
when_modified: Configure when Terrateam should trigger based on file changes
cost_estimation: Enable and configure cost estimation for Terraform plans
automerge: Automatically merge pull requests after successful applies

For a complete list of available options and their usage, refer to the configuration reference section of the documentation.