Turning a Terraform repository into a product

Make a shared repository usable across teams

The central Terraform repository held the company’s cloud infrastructure, but lacked the conventions needed to support a growing group of contributors. State files were committed to Git. Module tags used inconsistent names and had no changelogs. Finding the right stack or learning the release process depended on asking someone who already knew the repository.

I approached the work as a series of improvements to a shared product: state management first, then releases, structure, navigation, and support for the people using it.

Establish a predictable state and release model

I moved every stack’s state into S3 backends in one migration campaign. That separated Terraform’s resource state from the source code engineers reviewed.

Next I replaced manual module tags with automated releases. Structured commit messages determine the version change and produce a changelog. Each releasable component runs in an isolated release job, avoiding interference between releases in the monorepo. The resulting tags also gave dependency automation stable versions to track.

Formatting, linting, and documentation generation became automated checks. I rewrote the contributor documentation and recorded terminal walkthroughs so engineers could see the workflow being used.

Separate a stack’s identity from its deployments

I introduced Terramate, designed the shared imports and repository layout, and migrated legacy stacks into it. A simplified path illustrates the structure:

stacks/
  aws/
    development/
      eu-west-1/
        service-platform/
    production/
      eu-west-1/
        service-platform/

Shared imports generate backend and provider configuration. The deployment directory carries the configuration that varies by account and region. The migration runbook preserves the old state object as a rollback reference and verifies the new configuration through Atlantis before applying it.

As the inventory reached hundreds of stacks, directory conventions alone were insufficient. I built a terminal explorer that groups stacks by identity and shows where each is deployed, with evaluated account, region, and environment settings. It also exposes recent Git history and table, JSON, and CSV output for scripting. Browsing the inventory does not require cloud credentials or elevated access.

The recording uses a demonstration inventory. The implementation notes explain how the explorer resolves stack metadata.

Support adoption alongside the tooling

I started a Terraform community channel, answered beginner questions, and provided worked examples. That support made the conventions easier to adopt and gave me feedback about where the workflow remained confusing.

The internal provider registry later added a common distribution point for custom and mirrored providers.

What changed

The repository grew from dozens of stacks to hundreds while retaining one release process and a consistent way to discover deployments. Engineers across teams could propose infrastructure changes through the shared workflow, with reusable modules, documented conventions, and support available when the automation was not enough.