Your Terraform codebase started small. A few modules, maybe some environments split into directories. Now you're managing infrastructure across multiple teams, environments, and services. The question keeping you up at night: should everything live in one massive repository or split into smaller, focused repos?
This isn't just an organizational preference. Your repository structure directly impacts deployment speed, team autonomy, blast radius of changes, and your ability to enforce consistent policies across infrastructure. Get it wrong, and you'll spend months untangling dependencies or dealing with deployment bottlenecks.
The Monorepo Approach: Everything Under One Roof
A Terraform monorepo keeps all your infrastructure code in a single repository. Your directory structure might look like this:
terraform-infrastructure/
├── modules/
│ ├── vpc/
│ ├── eks-cluster/
│ └── rds/
├── environments/
│ ├── dev/
│ ├── staging/
│ └── prod/
├── services/
│ ├── api/
│ ├── frontend/
│ └── analytics/
└── shared/
├── networking/
└── security/
When Monorepos Work Well
Small to medium teams (3-15 engineers) benefit most from monorepos. Everyone sees the full infrastructure picture. Changes across multiple components happen in single pull requests. Code reviews catch cross-service impacts before they hit production.
Tightly coupled infrastructure fits naturally in monorepos. When your VPC changes affect every service, or your monitoring setup spans all environments, having everything in one place reduces coordination overhead.
Consistent tooling and policies are easier to enforce. Your CI/CD pipeline, linting rules, and security policies apply uniformly across all infrastructure code.
Monorepo Advantages
Atomic changes across components. Need to update your VPC and all the services that depend on it? One PR, one deployment, one rollback if things go wrong.
Simplified dependency management. No version pinning between repositories. No wondering which version of your VPC module works with which service configuration.
Easier refactoring. IDE search-and-replace works across your entire infrastructure. Moving shared resources between modules doesn't require coordinating multiple repositories.
Single CI/CD pipeline. One workflow to understand, maintain, and debug. Your GitHub Actions or GitLab CI configuration handles everything in one place.
Monorepo Challenges
Deployment bottlenecks emerge as teams grow. Only one team can deploy at a time if you're using a single state file. Even with workspace separation, CI/CD queues get long.
Blast radius concerns keep platform engineers awake. A bad merge to main can potentially impact every environment and service. Your staging deployment failure might block production hotfixes.
Access control complexity grows with team size. GitHub's repository-level permissions don't map well to "team A owns services X and Y, team B owns service Z." You end up with broad access or complex branch protection rules.
Large repository overhead slows down everyday operations. Cloning takes longer. IDE indexing struggles. CI/CD jobs download more code than they need.
The Polyrepo Approach: Focused Repositories
Polyrepos split infrastructure code across multiple repositories, typically organized by service, team ownership, or environment.
terraform-shared-infrastructure/
├── modules/
└── environments/
terraform-api-service/
├── infrastructure/
└── environments/
terraform-frontend-service/
├── infrastructure/
└── environments/
terraform-platform/
├── vpc/
├── monitoring/
└── security/
When Polyrepos Make Sense
Larger teams (15+ engineers) often need polyrepos to maintain velocity. Different teams deploy independently without stepping on each other. Ownership boundaries are clear from repository structure.
Service-oriented architectures map naturally to polyrepos. Each service team owns their infrastructure code alongside application code. Platform teams manage shared resources separately.
Different compliance requirements might force polyrepo adoption. Your payment processing service needs SOC 2 compliance, but your marketing site doesn't. Separate repositories make audit trails cleaner.
Polyrepo Advantages
Team autonomy increases deployment speed. Service teams deploy when they're ready, not when the platform team's changes are stable.
Reduced blast radius contains failures. A bad deployment in the analytics service won't break your API or frontend infrastructure.
Clear ownership boundaries simplify access control. Team permissions map directly to repositories. Code review assignments are obvious.
Faster CI/CD for individual services. Your API team's infrastructure changes don't wait for the frontend team's deployment to finish.
Polyrepo Challenges
Cross-service changes become coordination nightmares. Updating your VPC requires pull requests across multiple repositories, careful sequencing, and hope that everyone deploys in the right order.
Module versioning overhead slows down updates. Your shared VPC module lives in one repository, but every service repository pins to specific versions. Rolling out security updates takes weeks of cross-repo coordination.
Inconsistent tooling emerges over time. Each team picks their preferred linting rules, CI/CD patterns, and security policies. What started as flexibility becomes technical debt.
Dependency hell between repositories. Service A depends on outputs from Service B's infrastructure. Version mismatches cause deployment failures that are hard to debug.
Team Size and Structure Considerations
3-8 Engineers: Monorepo Sweet Spot
Small teams benefit from monorepos' simplicity. Everyone understands the full infrastructure. Code reviews catch cross-service issues. Coordination happens naturally through daily standups and Slack.
Your biggest risk is deployment bottlenecks, but with careful CI/CD design and Terraform workspaces, small teams rarely hit this limit.
8-15 Engineers: The Transition Zone
This is where architectural decisions get interesting. You might start with a monorepo and feel growing pains around deployment queues and blast radius concerns.
Consider a hybrid approach: shared infrastructure (VPC, monitoring, security) in one repository, service-specific infrastructure in separate repos. This gives you team autonomy where it matters while keeping shared resources centralized.
15+ Engineers: Polyrepo Territory
Large teams usually need polyrepos to maintain velocity. The coordination overhead of monorepos outweighs their benefits when you have multiple teams deploying daily.
Focus on tooling that reduces polyrepo pain points: shared module repositories, automated dependency updates, and consistent CI/CD patterns across repositories.
Migration Strategies
Monorepo to Polyrepo Migration
Start with service boundaries. Identify infrastructure that clearly belongs to specific teams or services. Extract these into separate repositories first.
Keep shared resources centralized initially. Your VPC, monitoring, and security infrastructure probably serve multiple teams. Don't split these until you have clear ownership and dependency management patterns.
Migrate incrementally. Don't try to split everything at once. Move one service at a time, validate the new workflow, then continue.
Plan for state management. Terraform state files need to move with the code. Use terraform state mv commands carefully, and always backup state before migrations.
Polyrepo to Monorepo Consolidation
Audit dependencies first. Map out which repositories depend on outputs from others. These dependencies become internal module relationships in your monorepo.
Standardize tooling before merging. Align CI/CD patterns, linting rules, and directory structures across repositories. This reduces merge conflicts and post-migration cleanup.
Merge related services together. Don't dump everything into one repository immediately. Start by combining closely related services, then gradually expand.
Enforcing Consistency Across Repository Structures
Regardless of your repository structure choice, you need consistent policies across your infrastructure code. Manual code reviews catch some issues, but they don't scale with team growth.
This is where automated guardrails become essential. Tools that integrate with your existing CI/CD pipeline can enforce cost limits, security policies, and operational best practices across all your Terraform code—whether it lives in one repository or dozens.
For teams managing multiple repositories, automated policy enforcement becomes even more critical. You need confidence that every repository follows the same security standards, cost controls, and operational practices without manually auditing each one.
Making the Right Choice for Your Team
Your repository structure should match your team structure and deployment patterns. Small, tightly coupled teams benefit from monorepos' simplicity. Larger, service-oriented teams need polyrepos' autonomy.
Consider these questions:
- How often do changes span multiple services or environments?
- Do teams deploy independently or in coordinated releases?
- How complex are your access control requirements?
- What's your tolerance for deployment bottlenecks vs coordination overhead?
Remember that you can change your mind. Many successful teams start with monorepos and split into polyrepos as they grow. Others consolidate polyrepos when coordination overhead becomes painful.
The key is choosing a structure that supports your current team size and deployment patterns while planning for reasonable growth. Don't optimize for problems you don't have yet, but don't paint yourself into architectural corners either.
Your repository structure is just the foundation. The real challenge is maintaining consistency, security, and operational excellence across your infrastructure code as your team and codebase evolve.
Ready to add automated guardrails to your Terraform workflow, regardless of your repository structure? Learn more at cloudonrails.com.