Using Git Tags for Module Versioning in Spacelift

Overview

In Spacelift, you can use Git tags to manage versioning for Terraform modules, allowing you to push module versions directly to the Spacelift module registry based on tag events. This article explains how to set up a Push policy to support tag-driven module releases.

Setting Up a Tag-Driven Release Flow with Push Policy

To use Git tags for module versioning, create a Push policy and attach it to your module. This policy detects tag events and automatically updates the module version based on the tag.

1. Configure the module_version Block in Your Push Policy
   The example policy below defines a module_version block that:

   • Extracts the version from the Git tag, Spacelift requires versioning in an X.X.X format.

   • Provides a placeholder version (<X.X.X>) for proposed runs to prevent check failures in pull requests when using existing versions.

   package spacelift 
   
   module_version := version {
     version := trim_prefix(input.push.tag, "v") 
     not propose 
     } 
   
   module_version := "<X.X.X>" {
     propose 
     } 
   
   propose { 
     not is_null(input.pull_request) 
   }

2. Add a Track Rule for Automatic Runs
   To start a tracked run when a new tag is pushed, use the following snippet to your policy. This example triggers a tracked run when the module_version is set (i.e., not empty) and the push branch matches the module’s tracking branch.

   track { 
     module_version != ""
     input.push.branch == input.module.branch
    }

   This rule ensures that only tag pushes on the main branch or the designated tracking branch will trigger a tracked run for the module.

Important Notes

• Tag Prefix Handling: The example above removes the "v" prefix from Git tags (e.g., v1.0.0 becomes 1.0.0) to ensure compatibility with Spacelift’s module versioning, which requires numeric X.X.X format.

• Mock Version for Proposed Runs: The policy uses a mock, non-existent version (<X.X.X>) during proposed runs to prevent issues in pull requests where existing versions might otherwise cause validation errors.