Versioning
How module releases are tagged, how apps pin a release, and how to upgrade safely.
Every merge to main that changes module code produces a new release tag. Apps pin a tag in each module source, so a change in this repository reaches an app only when its team bumps the tag and reviews the plan.
How releases are cut
The Release workflow in .github/workflows/release.yml runs on every push to main.
It skips changes that cannot affect an app. Pushes that only touch Markdown files, examples/, or .github/ do not trigger a release.
It bumps the minor version. The workflow finds the latest v* tag and adds one to the minor number, so v1.6.0 becomes v1.7.0. Releases never bump the patch or major number.
It updates the docs to match. The workflow rewrites every ?ref= in README.md and examples/*/main.tf to the new tag and commits the change.
It pushes the commit and the tag together. One atomic push sends both, so the README never points at a tag that does not exist.
Engineers can also start the workflow by hand from the Actions tab with workflow_dispatch.
Pin a release
Every module source ends with ?ref= and a tag. The module pages on this site fill in the latest tag for you.
module "alb" {
source = "git::ssh://git@github.com/the-kaizen-labs/terraform-modules.git//alb?ref=v1.7.0"
# ...
}Modules in one stack can pin different tags. ginkgo, for example, pins ecs-service at v1.6.0 and its other modules at v1.3.0. Each module page lists the tag every app pins under Used by.
Never pin ?ref=main
A stack that pins main picks up every merge the next time anyone runs terraform init. Two plans of the same commit can then differ, and a change to a shared module can reach every app at once. Pin a tag.
Upgrade a module
Read what changed. The repository has no changelog file. List the commits that touched the module between your tag and the new one, for example git log v1.6.0..v1.7.0 --oneline -- ecs-service/.
Bump the ref. Change ?ref= on that module's source, then run terraform init -upgrade to fetch the new code.
Read the plan. Open a pull request so CI posts the plan. Expect in place updates. Stop and investigate any replace of a database, cache, bucket, or load balancer.
Merge. The apply runs on merge, the same as any other infrastructure change.
New settings ship turned off when turning them on would change existing resources. For example, enable_fargate_capacity_providers on ecs-cluster and enable_audit_logging on rds-postgres both default to false for that reason. Where a module moved a resource to a new address, it includes moved blocks so Terraform updates state instead of recreating the resource.