Andrew Mercer
on this page

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:

  • moved blocks inside the module for internal renames. Callers upgrade with no state surgery (refactoring).
  • deprecated on variables and outputs (Terraform 1.15+, OpenTofu 1.11+) one minor release before removal.
  • import blocks 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.2 and 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:

  1. terraform init + validate + tflint
  2. terraform plan -detailed-exitcode against each environment
  3. 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

  1. 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.