Custom File Discovery with Tree Builder

Terrateam’s tree builder feature enables you to customize how files are discovered and tracked in your repository. This powerful capability allows you to implement custom change detection logic, work with dynamically generated Terraform files, and handle complex monorepo dependencies.

When to Use Tree Builder

Tree builder is particularly useful when Git’s standard file tracking doesn’t meet your needs. Consider using tree builder when you have:

Common Use Cases

• Dynamic Infrastructure - Terraform files generated from templates or code
• Complex Dependencies - Changes in shared libraries should trigger dependent services
• Custom Change Logic - Business rules that determine what counts as a “change”
• Non-standard Workflows - Infrastructure patterns that don’t fit traditional file tracking

How Tree Builder Works

Tree builder acts as a custom file discovery layer between your repository and Terrateam’s workflow engine. Instead of relying solely on Git to determine which files exist and have changed, your custom script provides this information.

Workflow Order

Tree builder is part of Terrateam’s execution pipeline and runs at a specific point in the workflow:

    
flowchart LR
  A[Indexer] --> B[Tree Builder]
  B --> C[Config Builder]
  C --> D[Plan/Apply]

  style B fill:#f9f,stroke:#333,stroke-width:2px
  style C fill:#9ff,stroke:#333,stroke-width:2px

  

1. Indexer - Discovers directories and initial file structure
2. Tree Builder - Custom file discovery and change detection
3. Config Builder - Dynamically generates runtime configuration
4. Plan/Apply - Executes Terraform operations on the final file set

Integration with Config Builder

Tree builder and config builder work together to create your final workflow:

• Tree Builder determines which files exist and what has changed
• Config Builder determines how to process those files

This separation allows you to customize file discovery without affecting your runtime configuration logic, or vice versa.

    
flowchart LR
  A[Git Repository] --> B[Tree Builder Script]
  B --> C[Custom File List]
  C --> D[Config Builder]
  D --> E[Runtime Configuration]
  E --> F[Plan/Apply Operations]
  
  style B fill:#f9f,stroke:#333,stroke-width:2px
  style C fill:#9ff,stroke:#333,stroke-width:2px
  style D fill:#ff9,stroke:#333,stroke-width:2px

  

Your tree builder script:

1. Analyzes the repository state
2. Applies custom logic to determine files and changes
3. Outputs a JSON structure that Terrateam uses for workflow decisions

Getting Started

1. Enable tree builder in your configuration

   Add the following to your .terrateam/config.yml:

   tree_builder:
     enabled: true
     script: "./scripts/discover_files.sh"

2. Create your discovery script

   Your script must output JSON to stdout with this structure:

   {
     "files": [
       {
         "path": "environments/prod/main.tf",
         "id": "a1b2c3d4e5f6789"
       },
       {
         "path": "environments/staging/main.tf",
         "id": "f9e8d7c6b5a4321"
       }
     ]
   }

   The id field is an opaque string that uniquely identifies each file (typically a hash of the file contents). Terrateam uses this identifier to determine if a file has changed by comparing the ID in the source branch with the ID in the destination branch. If the IDs differ, the file is considered changed.

3. Test your script locally

   Before deploying, ensure your script produces valid JSON:

   ./scripts/discover_files.sh | jq '.'

4. Deploy and monitor

   Push your changes and watch Terrateam use your custom file discovery in pull requests.

Best Practices

Security Considerations

• Validate all inputs to your script
• Avoid executing untrusted code
• Use secure file operations
• Restrict who can modify tree builder scripts using access_control

For detailed configuration options, see the tree builder configuration reference.