Terraform Module Template

Automate versioning, changelog generation, and publishing of Terraform modules to the GitLab Terraform Module Registry using semantic-release and Conventional Commits.

Setup

Recommended: External CI/CD Configuration

Go to Settings > CI/CD > General pipelines and set CI/CD configuration file to:

https://gitlab-ci-yaml-template.enouvo.com/terraform/.terraform-module.gitlab-ci.yml

Alternative: Include in .gitlab-ci.yml

include:
  - 'https://gitlab-ci-yaml-template.enouvo.com/terraform/.terraform-module.gitlab-ci.yml'

Add .releaserc.json

Create a .releaserc.json in your module's root:

{
  "branches": ["main"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    ["@semantic-release/changelog", { "changelogFile": "CHANGELOG.md" }],
    ["@semantic-release/git", {
      "assets": ["CHANGELOG.md"],
      "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
    }],
    ["@semantic-release/gitlab"]
  ]
}

Required Variables

Variable	Description
`GITLAB_CI_ACCESS_TOKEN`	Token to download ci-scripts (set by admin at group level)
`GITLAB_TOKEN`	Project access token with `api` + `write_repository` scope. Used by semantic-release to create tags/releases and push changelog.

Tip: Create a Project Access Token with Maintainer role and api + write_repository scopes. Add it as a CI/CD variable named GITLAB_TOKEN.

How It Works

1. Commit with Conventional Commits

Push commits to main using the Conventional Commits format:

Commit Message	Version Bump	Example
`feat: add WAF support`	Minor	0.1.0 → 0.2.0
`fix: correct S3 policy`	Patch	0.2.0 → 0.2.1
`feat!: rename web_hostname variable`	Major	0.2.1 → 1.0.0

2. Release Job (on push to main)

semantic-release runs and:

Analyzes commits since last tag
Determines the next version
Updates CHANGELOG.md
Creates a GitLab release + git tag (e.g. 1.0.0)
Pushes the changelog commit back with [skip ci]

3. Publish Job (on new tag)

The new tag triggers the publish job which:

Tars the module source
Uploads it to the GitLab Terraform Module Registry

Consuming the Module

Once published, use the module in other Terraform projects:

module "static_web" {
  source  = "gitlab.enouvo.com/devops/terraform-aws-static-web/aws"
  version = "~> 1.0"

  # module variables...
}

Pipeline Stages

release (on main push) → publish (on tag creation)

Project Structure

terraform-module/
├── main.tf
├── variables.tf
├── outputs.tf
├── versions.tf
├── CHANGELOG.md          (auto-generated)
├── .releaserc.json       (semantic-release config)
└── .gitlab-ci.yml        (or use external config)