Terramate Documentation

Terramate provides several core capabilities for managing IaC at scale:

• Orchestration & Change Detection: Run commands (like terraform apply) in stacks with high concurrency. Use change detection to only execute stacks that have actual changes in Git or referenced modules.
• Code Generation: Programmatically generate HCL, JSON, or YAML to keep configurations DRY.
• Dependency Management: Manage dependencies between environments using output sharing and a graph-based engine.
• Automation: Use pre-configured GitOps blueprints for GitHub Actions, GitLab CI/CD, BitBucket Pipelines, and Azure DevOps.
• Cloud Features (Terramate Cloud): Adds drift management, misconfiguration detection (500+ policies), asset inventory, audit trails, and Slack integrations.

The tgdeps program identifies all files and directories that Terragrunt modules depend on. You can run it from within a specific module directory or from the project root (such as the git repository root or stack directory).

$ tgdeps

Terramate can be added to existing infrastructure projects without refactoring. Depending on your current setup, follow the specific onboarding guide for your tool:

• Terraform: For existing Terraform projects.
• OpenTofu: For existing OpenTofu projects.
• Terragrunt: For existing Terragrunt projects.
• From Scratch: If you are starting a new project.

Terramate supports promoting bundles from a source environment to a target environment. A bundle is considered 'promotable' if:

1. The target environment has a PromoteFrom configuration pointing to a source environment.
2. The bundle exists in the source environment.
3. The bundle's alias does not already exist in the target environment.
4. All bundle references (dependencies) required by the bundle are also available/present in the target environment's aliases.

After selecting a bundle to promote, the UI enters the ViewPromoteInput state. This allows you to provide specific values for the bundle's input definitions before saving them to the target environment.

Key interactions in the input form:

• Tab: Switch between different input sections (if the form uses two panels).
• Esc:
  • If editing a multiline field or a sub-form: Exit the sub-form/edit mode.
  • If in the main form: Go back to the bundle selection list.
• Save (via form confirmation): Validates the inputs, creates a PromoteChange, and applies the changes to the target environment's registry.

When using the Terramate interactive UI for reconfiguring bundles, you can navigate through available bundle instances and filter them by environment.

Navigation

• Up/Down Arrows: Move the selection cursor through the list of bundles.
• Enter: Select a bundle to open its reconfiguration input form.
• Escape:
  • If a filter is active: Reset the filter to show all bundles.
  • If no filter is active: Go back to the Overview view.

Filtering

• e: Cycle through available environment filters (e.g., specific environments or "Without Environment"). This allows you to quickly narrow down the list of bundles to those belonging to a specific context.

When interacting with the Terramate CLI input forms, use the following patterns:

• Editing an existing value: Navigate to the 'Inputs' or 'Attributes' panel at the bottom, select a row, and press Enter to open its editor.
• Resetting a value: If you have modified a value, you can typically use del (delete) to reset it to its original state.
• Handling Sub-forms: When editing nested objects, a new form will appear. Once finished, the sub-form is accepted or discarded to return to the parent object's attributes.
• Confirming Changes: After filling all required inputs, look for inline buttons like [Confirm] [Cancel] or [Save] [Cancel] to commit your changes.