IaC repository types — single-tool versus multi-tool repositories

The first decision when you start an infrastructure codebase is not “how do I lay out my Terraform” - that comes later. The first decision is the repository boundary: how many repositories do you need, and what does each one own?

The two shapes

There are two practical shapes: a multi-tool repository that holds every IaC tool under one root (Terraform, Ansible, Kubernetes manifests, OPA policies, network config), and a single-tool repository where the cross-tool integration is done through tagged releases, submodules, or versioned artifacts.

flowchart LR
    subgraph MR["Multi-tool repository"]
        T1[terraform/]
        A1[ansible/]
        K1[kubernetes/]
    end
    subgraph SP["One repository per tool"]
        TR["infra-terraform"]
        AR["infra-ansible"]
        KR["infra-kubernetes"]
    end

The multi-tool shape is easier to start with: a new directory, a new CI matrix entry, a new reviewer group, and the team is unblocked. The split shape is easier to grow into: each tool has its own trunk, its own release cadence, its own reviewers, its own blast radius.

Trade-offs of a multi-tool repository

For a small team the multi-tool repository has real advantages:

• One pull request, one review surface. A service-onboarding PR that touches Terraform, Ansible, and Kubernetes manifests is reviewed as a single unit.
• One CI matrix. Every tool is a matrix entry in one pipeline.
• One set of secrets, one set of runners. Cloud and cluster credentials are loaded once per CI run.
• Easier refactors. Renaming a module or deleting a role happens across the whole codebase in a single commit.

The cost is a shared release cadence. When Terraform needs to be held while an Ansible change is reviewed, the whole team waits. When one tool’s CI is slow, every PR waits for it, and the trunk carries the slower tool’s churn.

Trade-offs of split repositories

One repository per tool flips the trade-offs:

• Independent release cadence. Terraform ships weekly while Ansible is frozen during a security review. The two trunks move at their own speed.
• Independent ownership. CODEOWNERS matches ownership, not the global team: platform owns Terraform, application-platform owns Kubernetes, the network team owns the network repository.
• Independent blast radius. A bad merge in the Ansible repository cannot block the Terraform trunk.
• Sharper review surface. A tool-expert reviewer reads only that repository, with full context, not a PR that mixes three tools.

The cost is cross-tool change coordination. A service-onboarding change that touches all three tools is now three pull requests, three reviews, three merges, and three deploys. The order of those three merges is a release-coordination problem the team has to solve.

When to split

A split is forced by one of three operational signals:

• Release cadence divergence. If Terraform ships weekly but Ansible is frozen for a month, the trunk is no longer reflecting reality. The slower tool is gating the faster one.
• Blast-radius divergence. A network change has a different blast radius than an application-platform change. Reviewers, approvers, and change windows cannot be the same.
• Ownership divergence. When two teams own the same repository and disagree about review policy, the disagreement surfaces in every PR and CODEOWNERS becomes a political document.

Production discipline

1. Default to one repository per team-owned IaC domain, not per tool. The boundary is the team’s boundary, not the tool’s.
2. Split when the release cadence diverges. A team that ships Terraform weekly and Kubernetes monthly needs at minimum two repositories, even if the same engineers write both.
3. Split when the blast radius diverges. Network and application configuration should never share a default branch.
4. Use submodules or versioned releases for cross-repo sharing. When a Terraform module is consumed by an Ansible role in another repository, the consumption is a pinned reference, not a git pull of latest.

Cross-course references

• Linux for Production Sysadmins - Part XXVI (RepoLayout) covers the filesystem analogue: one big /etc versus a per-service tree.
• Ansible for Production Sysadmins - Part XXXVII covers the role-based layout of a single-tool Ansible repository.
• Terraform for Production Sysadmins - Part IX (State) covers why Terraform is usually its own repository.

Quiz