Skip to main content


Terraform Automation

A typical Terraform change with Terrateam works like this:


These steps are verbose to provide a clear explanation of how Terrateam works

  1. Alice opens a pull request
  2. Terrateam GitHub Application triggers the Terrateam GitHub Actions workflow
  3. Terrateam GitHub Action executes a terrateam plan and comments the output to the pull request
  4. Bob reviews and approves the pull request
  5. Alice comments terrateam apply
  6. Terrateam GitHub Application triggers the Terrateam GitHub Actions workflow
  7. Terrateam GitHub Action executes a terrateam apply and comments the output to the pull request
  8. Alice reviews terrateam apply output and merges the pull request

Terrateam components can be customized using a configuration file that lives in your repository.


Terrateam commands can only be issued using GitHub Pull Request Comments.

Every Terrateam command starts with terrateam.

Directories, Workspaces, and Changes

Hierarchy of Repositories

Things to note:

  • The top is the repository
  • A repository can contain zero or more directories
  • A directory can contain one or more workspaces
  • If no workspace is specified then each directory has a default workspace
  • A workspace allows the contents of a directory to be used in different contexts
  • A workspace maps to a Terraform workspace


Every execution of a Terrateam operation (apply or plan) takes place in the context of a repository, a directory, and a workspace. This is sometimes denoted as a tuple (repository, directory, workspace), or (directory, workspace) for short, as the repository is usually implied. This tuple is referred to as dirspace, a combination of directory and workspace.

For example, a repository named repo with two directories in it, dir1 and dir2, and with no extra configuration for workspaces, would have two dirspaces:

  1. (repo, dir1, default) or (dir1, default)
  2. (repo, dir2, default) or (dir2, default)


A pull request contains changes to a repository.

Terrateam uses file_patterns in the when_modified global and dirs configurations to determine if a change in a pull request requires executing a Terrateam command. These changes are then mapped to their appropriate dirspace.


Consider the following:

  • A repository with a default Terrateam configuration
  • Directories in the repository:
    • tf-dir1
    • tf-dir2
    • tf-dir3
    • tf-dir4
    • docs

A pull request is opened with changes to the following files:

  • tf-dir1/
  • tf-dir3/
  • docs/

Given the default configuration of file_patterns: ['**/*.tf', '**/*.tfvars']

Terrateam will detect the following:

  • tf-dir1 and tf-dir3 have changes which require an automatic execution of terrateam plan
  • docs/ does not match file_patterns and will be ignored

The tf-dir1 and tf-dir3 changes map to the following dirspaces:

  • (tf-dir1, default)
  • (tf-dir3, default)

These dirspaces are called a change.

When it is stated that a terrateam plan or terrateam apply is being executed on the changes in a pull request, the changes refer to only those dirspaces that have files modified in the pull request.


Terrateam uses tags to both group elements of a repository together as well as match those elements when executing an operation.

Learn more