Skip to main content
RunBook Academy

← All runbooks in Terraform

low riskinformational~15 min

Runbook: Manage Module Versions and Releases

1 · Prerequisites

Confirm every item is in place before any state change.

  • A module in a Git repository
  • A versioning convention (e.g. semantic versioning)
  • A CI pipeline

2 · Pre-checks

Read-only diagnostic commands. If any of these don't match expected output, stop and investigate further.

  • · The module is in a Git repository
  • · The versioning convention is documented
  • · The CI pipeline is operational

3 · Procedure

Execute each step in order. Verify the expected output of a step before moving to the next.

  1. 1Update the module version
  2. 2Update the CHANGELOG
  3. 3Update the README
  4. 4Run the tests
  5. 5Tag the release
  6. 6Push the tag
  7. 7Document the release

4 · Verification

Confirm the procedure actually fixed the problem.

  • ✓The version is updated
  • ✓The CHANGELOG is updated
  • ✓The README is updated
  • ✓The tests pass
  • ✓The tag is pushed
  • ✓The release is documented

5 · Rollback

If verification fails, undo the procedure in reverse order.

  • ↶If the release breaks, revert the tag
  • ↶If the module is broken, revert the commit

6 · Escalation

When the runbook isn't enough, contact:

  • · If the module is in production, escalate to the engineering manager
  • · If the breaking change affects production, escalate to the incident commander

Purpose

This runbook walks through the management of module versions. The module is the unit of reuse; the version is the unit of reproducibility.

When to use this runbook

Use this runbook when:

  • A module is being prepared for a new release.
  • A breaking change is being introduced.
  • A new feature is being added.

Procedure

Step 1: Update the module version

Edit the module’s source. The version is typically a Git tag.

git checkout -b release-v1.2.0

Step 2: Update the CHANGELOG

Edit CHANGELOG.md:

# Changelog

## [1.2.0] - 2026-08-12

### Added
- New feature: ...

### Changed
- ...

### Fixed
- ...

Step 3: Update the README

Update the README to document the new version:

# Module

## Version

Current version: 1.2.0

## Changelog

See CHANGELOG.md.

Step 4: Run the tests

terraform test

The tests must pass.

Step 5: Tag the release

git tag -a v1.2.0 -m "Release 1.2.0"

Step 6: Push the tag

git push origin v1.2.0

Step 7: Document the release

The release is documented:

  • The version number.
  • The release notes.
  • The breaking changes.
  • The verification result.

Verification

The runbook is successful if:

  • The version is updated.
  • The CHANGELOG is updated.
  • The README is updated.
  • The tests pass.
  • The tag is pushed.
  • The release is documented.

Rollback

If the procedure fails:

  • Revert the tag.
  • Revert the commit.

Escalation

Escalate to:

  • Engineering manager if the module is in production.
  • Incident commander if the breaking change affects production.

References

  1. Module versioning