dirs

The dirs configuration can be used to describe which tag queries, workspaces, and when modified rules apply to a directory in your repository.

Default Configuration

dirs: {}

Keys

Each directory consists of the directory’s name as a key and a map as a value. The map has the following attributes:

Key	Type	Description
create_and_select_workspace	boolean	Create and select the workspace defined in the workspaces configuration. Default is true.
lock_branch_target	string	Defines when using destination_branches if this directory should be locked on a per-destination branch bases or all branches. all means that if two pull requests modify the same workspace, their locks will conflict with each other based on the destination branch name. dest_branch means that only pull requests modifying the same workspace targeting the same destination branch will conflict. Default is all.
tags	list	List of tags to assign the directory.
workspaces	object	Workspace configuration.
when_modified	when_modified	Configuration to override when to match pull request file changes with autoplan and autoapply.

Example Configuration

Here is an example of how directories might be configured:

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]

Directory Configuration

Create and Select Workspace

The create_and_select_workspace key is used to specify whether to select and create the workspace defined in the workspaces configuration.

Key	Type	Description
create_and_select_workspace	boolean	Select and create the workspace defined in the workspaces configuration. Default is true.

Tags

The tags key is used to create a custom tag for a directory. When assigning tags to a directory, tag values can be used in any combination to trigger workflows or target resources with a tag query.

Key	Type	Description
tags	list	List of tags to assign the directory.

Implicit Tags

dir:<name>

Each directory automatically receives a dir:<name> tag, where <name> is the path of the directory without a trailing /.

workspace:<name>

Each workspace automatically receives a workspace:<name> tag, where <name> is the name of the workspace.

Workspaces

The workspaces configuration is an object where the object key is the name of the workspace and the value is its configuration. Each workspace can have its own:

• Custom tags for targeting specific workspace operations
• when_modified configuration to override directory or global settings

Key	Type	Description
workspaces	object	Workspace configuration.
workspaces.<name>.tags	list	List of tags to assign to the workspace.
workspaces.<name>.when_modified	object	Workspace-specific when_modified configuration.

Example

dirs:
  infrastructure:
    tags: [aws]  # Directory-level tag
    workspaces:
      production:
        tags: [critical, prod]  # Workspace-specific tags
        when_modified:
          file_patterns: ["${DIR}/*.tf", "shared/*.tf", "modules/*.tf"]
          autoplan: true
          autoapply: true
      staging:
        tags: [non-critical, staging]  # Different tags for staging
        when_modified:
          file_patterns: ["${DIR}/*.tf", "shared/*.tf"]
          autoplan: true
          autoapply: false  # No auto-apply for staging

This example demonstrates:

• Directory-level tags (aws) apply to all workspaces
• Each workspace has its own tags (critical/prod vs non-critical/staging)
• Each workspace has custom when_modified rules (production is triggered by more file patterns and has auto-apply enabled)

When Modified

The when_modified configuration can be set at multiple levels within the dirs directive:

1. Directory level: dirs.<directory>.when_modified - Applies to ALL workspaces within that directory, overriding the global when_modified settings
2. Workspace level: dirs.<directory>.workspaces.<workspace>.when_modified - The most specific level, applies only to that individual workspace, overriding both global and directory-level settings

Key	Type	Description
when_modified	object	Configuration to override when to match pull request file changes with autoplan and autoapply.

Configuration Hierarchy

• The when_modified configuration syntax is identical across all levels (global, directory, and workspace)
• More specific configurations override broader ones: workspace > directory > global
• Individual keys can be overridden at each level (e.g., you can set only autoapply: true at the workspace level while other settings come from higher levels)
• The file_patterns default value is set to the path of the directory specified in the dirs object
• The file_patterns list is always relative to the root of the repository
• The ${DIR} variable specified in file_patterns is always relative to the root of the repository and can be used to specify the directory that Terrateam is working against

Examples

Directory-Level Configuration

dirs:
  foobar:
    when_modified:
      file_patterns: ["${DIR}/*.tf"]

This triggers a Terrateam plan operation when foobar/*.tf is modified in a pull request.

Workspace-Level Configuration

dirs:
  foobar:
    workspaces:
      production:
        when_modified:
          file_patterns: ["${DIR}/*.tf", "shared/*.tf"]
          autoplan: true
          autoapply: true
      staging:
        when_modified:
          file_patterns: ["${DIR}/*.tf"]
          autoplan: true
          autoapply: false

This example shows different when_modified configurations for production and staging workspaces within the same directory. The production workspace will autoplan and autoapply when either directory-specific or shared files change, while staging will only autoplan (not autoapply).

Globs

The dirs directive supports glob patterns, which can be useful for repositories with a lot of directories that match a pattern with a similar configuration.

Example

Consider a repository with the following files:

• _templates/ec2/terragrunt.hcl
• prod/ec2/us-east-1/foo.tf
• prod/ec2/us-west-1/foo.tf
• prod/ebs/us-east-1/foo.tf
• prod/ebs/us-west-1/foo.tf
• .terrateam/config.yml:

dirs:
  _templates/**:
    when_modified:
      file_patterns: []
  prod/**/ec2/**:
    tags: [prod, ec2]
    when_modified:
      file_patterns: ["_templates/**/*.tf", "${DIR}/*.tf"]
  prod/**:
    tags: [prod]
    when_modified:
      file_patterns: ["_templates/**/*.tf", "${DIR}/*.tf"]

Given the file list, the following dirs directive will be automatically generated during every Terrateam operation:

dirs:
  _templates/ec2:
    when_modified:
      file_patterns: []
  prod/ec2/us-east-1:
    tags: [prod, ec2]
    when_modified:
      file_patterns: ["_templates/**/*.tf", "prod/ec2/us-east-1/*.tf"]
  prod/ec2/us-west-1:
    tags: [prod, ec2]
    when_modified:
      file_patterns: ["_templates/**/*.tf", "prod/ec2/us-west-1/*.tf"]
  prod/ebs/us-east-1:
    tags: [prod]
    when_modified:
      file_patterns: ["_templates/**/*.tf", "prod/ebs/us-east-1/*.tf"]
  prod/ebs/us-west-1:
    tags: [prod]
    when_modified:
      file_patterns: ["_templates/**/*.tf", "prod/ebs/us-west-1/*.tf"]

Longest Glob Match

In the example above, the files in the prod/ec2 directory match two globs:

• prod/**/ec2/**
• prod/**

The glob prod/**/ec2/** is longer than prod/** and is considered the better match because the glob is more specific.

Directory Globs Match Files (Terragrunt)

Globs can be expressed all the way to the file level. The directory of the file is then taken when constructing the dirs directory. For example, in a repository with a structure to be used with Terragrunt, one could have the following configuration:

dirs:
  _templates/**/terragrunt.hcl:
    when_modified:
      file_patterns: []
  "**/terragrunt.hcl":
    tags: [terragrunt]
    when_modified:
      file_patterns: ['_templates/**/terragrunt.hcl', '${DIR}/*.hcl', '${DIR}/*.tf', '${DIR}/*.tfvars']

This configuration would apply the following rules:

• Lines 2-4: Disable Terrateam operations in any directory under the _templates/ directory with a terragrunt.hcl file.
• Lines 5-8: Run Terrateam operations against a directory when:
  • The directory contains a terragrunt.hcl file.
  • The pull request changed files ending in hcl, tf, or tfvars.
  • The pull request changed files include a terragrunt.hcl file in the _templates/ directory.

Longest glob wins.

Best Practices

• Assign tags to specific directories.
• Configure workspaces for specific directories.
• Override when_modified rules for specific directories.
• Use globs to match multiple directories with similar configurations.
• Use the ${DIR} variable to reference the current directory in file patterns.