Configuration

Terrateam uses a .terrateam/config.yml file to customize how it interacts with your GitHub repository and Terraform code.

Do I need a config file?

Terrateam uses sensible defaults if .terrateam/config.yml doesn’t exist. Add a config file only if you need custom workflows, OIDC, policies, or other advanced settings.

Basic Structure

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

access_control:
  # Specifies user permissions for operations
apply_requirements:
  # Defines preconditions for applying changes
dirs:
  # Maps directories to tags, workspaces, and behaviors
hooks:
  # Executes custom commands before or after operations
workflows:
  # Configures specialized plan and apply steps

Each section serves a specific purpose in customizing Terrateam’s behavior:

• access_control: Controls who can run plan and apply operations
• apply_requirements: Defines conditions that must be met before changes can be applied
• dirs: Maps your repository’s directory structure to Terrateam’s concepts
• hooks: Allows custom actions before or after operations
• workflows: Creates specialized processing for different workspaces

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: ''  # Empty string matches all workspaces
      plan: ['*']    # Anyone can plan
      apply: ['team:sre']  # Only SRE team members can apply

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

Access the Access Control page to see the complete list of configurations available.

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 with explanations:

apply_requirements:
  # Creates a status check that prevents merging until apply is complete
  create_pending_apply_check: true

  checks:
    - tag_query: ""  # Apply to all workspaces

      # Requires PR approvals
      approved:
        enabled: true        # Enable approval checking
        any_of: []           # No specific approvers required
        any_of_count: 2      # Requires at least two approvals
        all_of: []           # No mandatory approvers

      # Prevents apply if merge conflicts exist
      merge_conflicts:
        enabled: true

      # Requires all status checks to pass
      status_checks:
        enabled: true              # Enable status check verification
        ignore_matching:           # Regex patterns for checks to ignore
          - "ci/.*"                # Ignores all CI status checks

This configuration requires that the pull request has at least two 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 Terrateam Apply GitHub status check. Combined with GitHub Rulesets, this prevents the pull request from being merged until all Apply operations have completed.

See Apply Requirements for details.

Dirs

Dirs allow you to define which Tags, Workspaces, and When Modified rules apply to specific directories in your repository.

Here’s an example dirs configuration:

dirs:
  ec2:  # Directory name (relative to repository root)
    tags: [aws, ec2]  # Directory-level tags
    workspaces:
      production:  # Workspace name
        tags: [production]  # Workspace-specific tags
    when_modified:
      file_patterns: ["${DIR}/*.tf", "${DIR}/*.tfvars", "iam/*.tf", "iam/*.tfvars"]
  iam:
    tags: [aws, iam]

This configuration:

1. Assigns directory-level tags aws and ec2 to the ec2 directory
2. Assigns directory-level tags aws and iam to the iam directory
3. Creates a production workspace for the ec2 directory with the tag production
4. Specifies custom file patterns that, when modified, will trigger Terrateam operations for the ec2 directory

Directory vs. Workspace Tags

• Directory tags (tags at the directory level) apply to all operations in that directory across all workspaces
• Workspace tags (tags under a specific workspace) only apply when operating on that specific workspace
• Tags are used in tag queries (like tag_query: "aws") to target specific operations

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.

See Dirs for details.

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:  # Apply to all operations (plan & apply)
    pre:  # Run before the operation
      - type: run
        cmd: ['echo', 'Running pre-hook for all operations']
  plan:  # Apply only to plan operations
    post:  # Run after the operation
      - type: run
        cmd: ['echo', 'Running post-hook for plan operations']

See Hooks for details.

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 a basic workflow that slightly modifies the default behavior:

workflows:
  # Apply to all workspaces
  - tag_query: ""
    plan:
      - type: init  # Run terraform init
      - type: plan  # Run terraform plan
    apply:
      - type: init  # Run terraform init
      - type: apply # Run terraform apply

This simple workflow explicitly defines the standard Terraform workflow steps.

1. Initialization(init): Runs terraform init to prepare the directory for planning or applying changes.
2. Planning(plan): Runs terraform plan to generate an execution plan for the changes.
3. Apply(apply): Applies the changes to the infrastructure.

For more complex scenarios, you can create specialized workflows, such as the next one:

workflows:
  # This workflow applies to any directory tagged with "production"
  - tag_query: "production"
    plan:
      - type: init  # Run terraform init
      - type: plan  # Run terraform plan
        extra_args: ["-var-file=production.tfvars"]  # With these extra arguments
    apply:
      - type: init  # Run terraform init for apply
      - type: apply  # Run terraform apply
      - type: run   # Run a custom command
        cmd: ['echo', 'Error running apply']
        run_on: failure  # Only if apply fails

This advanced workflow runs a custom plan and apply process for any directories tagged with production. It adds production-specific variables during planning and executes error handling after failed applies.

See Workflows for details.

Other Configuration Options

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

• engine: Set the IaC tool to be used for operations.
• 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

See the Configuration Reference for a complete list of available options.

Basic Example

Here’s a complete example of a config.yml file containing a basic workflow that combines the configurations from the previous sections:

# Basic Terrateam configuration example
access_control:
  policies:
    - tag_query: ''  # All directories and workspaces
      plan: ['*']    # Anyone can plan
      apply: ['team:infra', 'team:platform']  # Only specific teams can apply

apply_requirements:
  create_pending_apply_check: true
  checks:
    - tag_query: ""  # All directories
      approved:
        enabled: true
        any_of_count: 1  # Requires at least 1 approval

dirs:
  staging:
    tags: [aws, staging]
  production:
    tags: [aws, production, critical]
    workspaces:
      default:
        tags: [default]

hooks:
  all:
    pre:
      - type: run
        cmd: ['echo', 'Starting Terraform operation']

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

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

This configuration:

1. Allows anyone to plan, but only members of infra or platform teams to apply.
2. Requires at least one approval before applying.
3. Defines staging and production directories with appropriate tags.
4. Runs a simple pre-hook for all operations.
5. Uses custom workflows for staging and production environments, applying the appropriate variable files.

You can start with a basic configuration like this and gradually add more advanced features as your deployment needs grow.