Private Module Registry

Terraform Registry protocol, Git sources, semantic versions, and release automation — hosting internal modules.

7 min readInfrastructure as CodeProvision

Registry Options

Option	Complexity	Features
Terraform Cloud	Low	UI, RBAC, versioning, policy
GitLab Terraform Registry	Medium	Package registry integration
GitHub with Terraform	Medium	Release-based versioning
Custom registry	High	Full control over protocol

Terraform Cloud Registry

Using Terraform Cloud modules


module "vpc" {
  source  = "app.terraform.io/my-org/vpc/aws"
  version = "~> 2.0"

  cidr = "10.0.0.0/16"
}

The source format is app.terraform.io/org/module/provider. Terraform Cloud hosts modules as a private registry. Authentication uses API tokens.

Git Module Sources

Git source patterns


# GitHub repository
module "vpc" {
  source = "git::https://github.com/org/terraform-modules.git//modules/vpc?ref=v2.0.0"
}

# GitLab repository
module "vpc" {
  source = "git::https://gitlab.com/org/modules.git//vpc?ref=v2.0.0"
}

# Bitbucket
module "vpc" {
  source = "git::https://bitbucket.org/org/modules.git//modules/vpc?ref=v2.0.0"
}

# SSH authentication
module "vpc" {
  source = "git::ssh://git@github.com/org/modules.git//modules/vpc?ref=v2.0.0"
}

Git sources use the double-slash syntax for subdirectories. The ref parameter specifies the version (tag, branch, or commit). SSH sources require SSH key authentication.

Release Automation

GitHub Actions release automation


name: Module Release
on:
  push:
    tags: ['v*']

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Create GitHub Release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{ github.ref }}
          release_name: ${{ github.ref }}
          body: |
            ## Changes
            See CHANGELOG.md for details

      - name: Update documentation
        run: |
          terraform-docs markdown table modules/vpc > modules/vpc/README.md

The release workflow triggers on version tags. It creates a GitHub release and updates documentation. This automates the module publishing process.

Access Control

Terraform Cloud RBAC — control who can publish and consume modules.
Git repository permissions — branch protection for module repositories.
API tokens — use team tokens for CI, not personal tokens.
Module visibility — restrict which modules are available to which teams.

Best Practices

Use semantic versioning for all module releases.
Pin to specific versions in production (version = 2.0.0).
Use ~> for development (version = ~> 2.0).
Automate documentation generation with terraform-docs.
Maintain a CHANGELOG for each module.
Test module releases before publishing.

Start with Git sources, graduate to a registry

Git sources work well for small teams. When module consumption grows, graduate to Terraform Cloud or GitLab registry. The migration is straightforward — change the source URL.

Git sources do not enforce versioning

Git sources use ref for versioning, but there is no enforcement. Anyone can update a tag. Use a registry for production modules where version integrity matters.

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.

Stage 4 · Provision

Modules & Composition