Shared modules turn into a maintenance problem once enough repos consume them. The common failure: a shared module pinned by exact version in 50–60 application repos, and every release needs someone to open 50–60 merge requests by hand. Nobody does, so repos drift a dozen versions behind, and the eventual upgrade is a big-bang migration.
The fix is a pipeline: semver releases → a registry → version constraints that allow safe updates → a bot that opens upgrade MRs → CI that plans them → auto-merge for the safe ones.
1. Choose how modules are distributed¶
| Option | Consumer syntax | Pros | Cons |
|---|---|---|---|
| Git tags | source = "git::https://gitlab.com/acme/tf-azure-network.git?ref=v3.2.1" |
No infrastructure; works everywhere | No version constraints, only exact refs; slow init on big repos |
| GitLab Terraform Module Registry | source = "gitlab.example.com/acme/network/azurerm" + version = "~> 3.2" |
Real constraints; lives with your code and CI; auth via job token | GitLab-specific auth setup |
| HCP Terraform private registry | source = "app.terraform.io/acme/network/azurerm" |
Integrated with HCP workspaces, no-code modules | Requires HCP Terraform |
| OCI registry (OpenTofu 1.10+) | source = "oci://..." |
Reuses container registry infra (ACR, Harbor) | OpenTofu only |
| Monorepo, relative paths | source = "../../modules/network" |
Atomic changes; no versions to bump | Every consumer always gets HEAD; no staged rollout |
A registry is what makes version = "~> 3.2" possible, and constraints are what make automated upgrades safe. If you're on Git tags today, moving to a registry is the highest-leverage change.
Publishing to the GitLab registry from CI¶
One repository per module (tf-azure-network), tagged with semver. On tag, publish:
# .gitlab-ci.yml in the module repo
include:
- template: Terraform-Module.gitlab-ci.yml # GitLab's maintained template
variables:
TERRAFORM_MODULE_NAME: network
TERRAFORM_MODULE_SYSTEM: azurerm # the "provider" segment of the address
TERRAFORM_MODULE_VERSION: ${CI_COMMIT_TAG} # the registry wants bare semver (3.2.1); see below
The template uploads to /api/v4/projects/:id/packages/terraform/modules/:name/:system/:version/file. Check the template's current variable names in your GitLab version, and whether it expects tags with or without a leading v. Many teams strip it: TERRAFORM_MODULE_VERSION: ${CI_COMMIT_TAG#v} in a script step.
Consumers authenticate with a token in ~/.terraformrc or an environment variable:
# Hostname dots become underscores
export TF_TOKEN_gitlab_example_com="${CI_JOB_TOKEN}"
module "network" {
source = "gitlab.example.com/acme/network/azurerm"
version = "~> 3.2"
}
2. Version modules with semver, strictly¶
| Bump | When | Examples |
|---|---|---|
| MAJOR | Callers must change something, or the plan destroys/replaces resources | Renamed/removed variable or output; changed default that forces replacement; provider major bump |
| MINOR | New capability, backwards compatible | New optional variable; new output; new optional resource behind a flag |
| PATCH | Fix with no interface change and no unexpected replacements | Bug fix; doc change; default change that's a no-op for existing resources |
The rule that matters most: a release that would replace or destroy resources in an unchanged caller is a major release, even if the interface didn't change. Your consumers' auto-merge policy depends on this promise.
Make breaking changes cheaper:
movedblocks inside the module for internal renames. Callers upgrade with no state surgery (refactoring).deprecatedon variables and outputs (Terraform 1.15+, OpenTofu 1.11+) one minor release before removal.importblocks inside the module (Terraform 1.16+) when a new version adopts existing resources.- A CHANGELOG.md with an "Upgrade notes" section for every major.
Automate releases from commit messages with semantic-release or release-please (Conventional Commits: feat: → minor, fix: → patch, feat!: / BREAKING CHANGE: → major).
3. Use constraints that accept safe updates¶
| Constraint | Means | Use in |
|---|---|---|
= 3.2.1 / 3.2.1 |
Exactly this | Rarely. Prevents patch fixes |
~> 3.2.1 |
>= 3.2.1, < 3.3.0: patches only |
Conservative roots |
~> 3.2 |
>= 3.2, < 4.0: minors and patches |
Most consumers |
>= 3.2, < 4.0 |
Same, spelled out | Module-to-module constraints |
>= 3.2 |
Anything newer, including majors | Don't |
Note: module versions aren't recorded in .terraform.lock.hcl; only providers are. With ~> 3.2, a fresh terraform init in CI picks up 3.9 the day it's published. That's the point (patches flow), but it also means you need a record of what was planned. Two approaches:
- Constraint + bot (recommended): consumers use
~> 3.2and Renovate keeps the floor current (~> 3.7), so the MR history shows when each repo moved. - Exact pin + bot: consumers pin exactly and Renovate opens a bump MR for every release. Maximum reproducibility, more MRs. This is what you have today, minus the bot.
Either way, the bot is what removes the manual work.
4. Automate upgrades with Renovate¶
Renovate's terraform manager understands registry modules, Git ?ref= tags, providers and required_version. Run it as a scheduled GitLab CI job (renovate/renovate image) against all infrastructure repos.
{
"$schema": "https://docs.renovatebot.com/renovate-schema.json",
"extends": ["config:recommended"],
"enabledManagers": ["terraform"],
"hostRules": [
{
"matchHost": "gitlab.example.com",
"hostType": "terraform-module",
"token": "{{ secrets.GITLAB_TOKEN }}"
}
],
"packageRules": [
{
"description": "Internal modules: group per module, auto-merge patches and minors after a clean plan",
"matchDatasources": ["terraform-module"],
"matchPackageNames": ["/acme//"],
"groupName": "internal module {{depName}}",
"matchUpdateTypes": ["minor", "patch"],
"automerge": true,
"automergeType": "pr",
"platformAutomerge": true
},
{
"description": "Majors always need a human",
"matchUpdateTypes": ["major"],
"automerge": false,
"labels": ["breaking-module-upgrade"]
},
{
"description": "Providers: weekly batch",
"matchDatasources": ["terraform-provider"],
"groupName": "terraform providers",
"schedule": ["before 6am on monday"]
}
]
}
What makes auto-merge safe is the consumer's MR pipeline:
terraform init+validate+tflintterraform plan -detailed-exitcodeagainst each environment- A policy check that fails the pipeline if the plan contains any delete or replace for a minor/patch bump:
bash
terraform show -json tfplan > tfplan.json
jq -e '[.resource_changes[] | select(.change.actions | index("delete"))] | length == 0' tfplan.json
- Platform auto-merge only if everything is green.
A minor bump that produces a no-op or additive plan merges itself. A bump that wants to replace something stops and waits for a person, which is exactly when you want a person.
Renovate renames config options from time to time (matchPackagePatterns became regex values in matchPackageNames, for example). Run renovate-config-validator in CI on the config repo so a Renovate upgrade can't silently disable your rules.
Renovate's equivalents: Dependabot (GitHub-centric, supports Terraform), and Terragrunt-aware setups that bump ?ref= in terragrunt.hcl (Renovate's terragrunt manager).
5. Track version currency¶
Know where every consumer stands. A nightly job can grep every repo's module sources and versions and publish a table:
| Repo | network | keyvault | app-service |
|---|---|---|---|
| infrastructure.logging | 3.9.0 ✅ | 2.4.1 ✅ | n/a |
| app-billing | 3.2.1 ⚠️ | 2.1.0 ⚠️ | 5.0.0 ✅ |
Pair it with a support policy: the latest two majors are supported; older majors get no fixes. That turns "please upgrade" from a request into a rule.
This is a natural fit for a small Rust CLI in the same family as your other tools: walk the repos (GitLab API), parse module blocks (the hcl-rs crate parses HCL), compare against the registry's latest, and output Markdown or JSON. Renovate's Dependency Dashboard issue gives you a per-repo version of this for free.
6. Release flow end to end¶
flowchart LR
A[Module MR] --> B[CI: fmt, validate, tflint, terraform test, example plan]
B --> C[Merge to main]
C --> D[semantic-release tags vX.Y.Z]
D --> E[Publish to GitLab registry]
E --> F[Renovate opens MRs in consumer repos]
F --> G[Consumer CI: plan per env + no-delete check]
G -->|minor/patch, clean| H[Auto-merge]
G -->|major or replaces| I[Human review]
H --> J[Normal promotion dev → test → prod]
I --> J
Consumers still promote through environments as usual (CI/CD); the bot only removes the toil of opening the MRs.
Monorepo alternative¶
If modules and all their consumers live in one repo with relative source paths, there are no versions to bump: a module change and every consumer's adjustment land in one MR. The trade-off is that every environment runs the module at HEAD, so you can't roll a module change through dev before prod by version. You stage it by applying environments in order instead. That works well for a small platform team owning everything; it scales badly across many independent app teams.