Skip to content

User Guide

Learn how to use Cultivator to automate Terragrunt workflows in CI and locally.

Sections

Quick Overview

Cultivator is a lightweight CLI that discovers Terragrunt stacks and orchestrates execution:

  1. Call cultivator
  2. Discovers stacks
  3. Applies filters
  4. Executes Terragrunt
  5. Shows results

Use Cases

Local Development

Run plans locally to validate changes before committing:

cultivator plan --root=live --env=dev

Pull Request CI

Test changes safely on PRs—no approval required until review:

# GitHub Actions or GitLab CI can run this automatically
cultivator plan --root=live --env=dev --non-interactive

Main Branch Deployment

Apply approved changes after merging to main:

cultivator apply --root=live --env=prod --non-interactive --auto-approve

Cross-Environment Promotion

Test in one environment, apply in others:

# Test in staging
cultivator plan --root=live --env=staging --tags=critical

# Apply to production after manual approval
cultivator apply --root=live --env=prod --tags=critical --auto-approve

Key Concepts

Stack Discovery

Cultivator recursively walks the root directory, finds all terragrunt.hcl files, and maintains a registry of available stacks.

Scope Filters

Use multiple filters to narrow execution:

  • --env=dev - by environment name
  • --include=envs/prod/* --include=envs/staging/* - by path pattern
  • --exclude=experimental - exclude paths
  • --tags=critical,prod - by inline tags (recommended: # cultivator:tags = critical,prod)

Dependency Ordering

Cultivator parses dependency blocks in Terragrunt configs and runs stacks in the correct order automatically.

Parallelism

Run independent stacks concurrently. Default: number of CPUs. Override with --parallelism=N.

Integration Paths

GitHub Actions

Add a workflow file to run Cultivator on PR and main branch:

  • See GitHub Actions for setup and examples
  • Features: matrix strategies, secrets integration, caching, artifacts

GitLab CI/CD

Define jobs in .gitlab-ci.yml to orchestrate Cultivator:

  • See GitLab Pipelines for setup and examples
  • Features: parallel jobs, dependency stages, caching, environment-based deployment

Local CLI Usage

Run Cultivator directly in your terminal:

  1. Build from source or download binary
  2. Execute: ./cultivator plan --root=live --env=dev
  3. Review output and commit changes

Getting Help