Your team keeps several Terraform modules in one Git repository. How do consumers reference just one of them, and how should you tag releases so each module can be pinned independently?

## Referencing one module out of many Terraform's remote source addresses support a subdirectory selector written with a double slash. Terraform fetches the whole package — here, a Git clone — and then uses only the named directory as the module: ```hcl module "vpc" { source = "git::ssh://[email protected]/acme/terraform-modules.git//modules/vpc?ref=vpc/v1.2.0" } ``` Everything before `//` identifies the package; everything after it is a path inside that package; query parameters configure the fetcher. This is the mechanism that makes a module monorepo possible at all. ## Why tagging is the hard half A Git tag points at a commit, and a commit belongs to the entire repository. There is no such thing as a tag on a folder. So with a single `v1.2.0` series: - Releasing a change to one module bumps the version number that *every* module shares. - A consumer of an untouched module either stays behind on an old tag or moves to a tag whose changelog is about someone else's module. - You cannot tell from the version number whether anything you depend on actually changed. The conventional workaround is a namespaced tag per module. Git tag names may contain slashes, so `vpc/v1.2.0` and `rds/v3.0.1` coexist happily and each consumer pins its own: ```hcl module "vpc" { source = "git::…/terraform-modules.git//modules/vpc?ref=vpc/v1.2.0" } module "db" { source = "git::…/terraform-modules.git//modules/rds?ref=rds/v3.0.1" } ``` Note that the same repository is now cloned under two different refs, which is fine — Terraform keeps each resolved module separately in `.terraform/modules`. ## What the release process has to do Prefixed tags only help if something enforces them. A workable process: 1. On merge, determine which module directories changed (a path filter over the diff). 2. For each changed directory, decide the semver bump — patch for a fix, minor for a backwards-compatible input or output, major for a removed or renamed input, a changed default that moves resources, or anything that makes a consumer's plan destroy something. 3. Create `<module>/vMAJOR.MINOR.PATCH` on the merge commit and publish a changelog entry scoped to that module. The failure mode when this is manual is predictable: someone edits two modules in one commit, tags only one, and the other module's consumers silently pick up an untagged change the next time they move their ref. ## Semver as a contract, not decoration Whatever the tag layout, the number has to mean something to consumers, and for a Terraform module the meaning is *what will this do to my plan*. A change that only adds an optional variable with a default is a minor bump. A change that renames a resource address inside the module is a major bump, because a consumer's plan will show a destroy and create unless the module ships refactor declarations to move the old addresses to the new ones. Treating a plan-destroying change as a patch is how a module ecosystem loses the trust that pinning was supposed to buy. ## The registry alternative The public Terraform Registry expects one module per repository, named `terraform-<PROVIDER>-<NAME>`, and derives versions from plain semver tags — which is exactly why monorepos are normally consumed by Git source rather than published to it. If you want the registry's version list, `~>` constraint resolution and generated documentation, the shape of your repositories is part of the price. ## When a monorepo is still right Monorepos win when the modules are genuinely developed together: one pull request can change a module and its callers, review happens in one place, and shared test scaffolding lives beside the code. They lose when the modules have independent consumers and independent release cadences, because then every one of the problems above is a weekly tax. Decide on lifecycle coupling, not on how many repositories you like looking at.