Skip to content


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 controls
# Apply requirements
# Repository layout definitions
# Hooks
# 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:

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

enabled: true
count: 2
enabled: true
enabled: true
- "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 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:

tags: [aws, ec2]
tags: [production]
file_patterns: ["ec2/*.tf", "ec2/*.tfvars", "iam/*.tf", "iam/*.tfvars"]
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 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:

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

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


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:

- tag_query: "dir:production"
- type: init
- type: plan
extra_args: ["-var-file=production.tfvars"]
- 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.

We use cookies and similar technologies to provide certain features, enhance the user experience and deliver content that is relevant to your interests. Depending on their purpose, analysis and marketing cookies may be used in addition to technically necessary cookies. By clicking on "Agree and continue", you declare your consent to the use of the aforementioned cookies. Here you can make detailed settings or revoke your consent (in part if necessary) with effect for the future. For further information, please refer to our Privacy Policy .