Add calendar-versioned release automation (#41)

Author: silv-io

.github/workflows/ci.yml

@@ -4,6 +4,8 @@ on:
   push:
     branches:
       - main
+    tags:
+      - "*.*.*"
   pull_request:
   workflow_dispatch:
 
@@ -30,6 +32,20 @@ jobs:
         with:
           version-file: .tool-versions
 
+  goreleaser-check:
+    name: GoReleaser Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Run GoReleaser check
+        uses: goreleaser/goreleaser-action@v6
+        with:
+          distribution: goreleaser
+          version: "~> v2"
+          args: check
+
   test-unit:
     name: Unit Tests
     runs-on: ubuntu-latest
@@ -102,3 +118,42 @@ jobs:
           name: Integration Test Results (${{ matrix.os }})
           path: test-integration-results.xml
           reporter: java-junit
+
+  release:
+    name: Build and Publish Release
+    if: startsWith(github.ref, 'refs/tags/')
+    needs:
+      - lint
+      - goreleaser-check
+      - test-unit
+      - test-integration
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+          cache-dependency-path: go.sum
+
+      - name: Validate CalVer tag
+        run: |
+          if [[ ! "${GITHUB_REF_NAME}" =~ ^[0-9]{4}\.[1-9][0-9]*\.[0-9]+$ ]]; then
+            echo "Tag '${GITHUB_REF_NAME}' does not match CalVer format YYYY.M.patch"
+            exit 1
+          fi
+
+      - name: Run GoReleaser
+        uses: goreleaser/goreleaser-action@v6
+        with:
+          distribution: goreleaser
+          version: "~> v2"
+          args: release --clean
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/create-release-tag.yml

@@ -0,0 +1,74 @@
+name: Create Release Tag
+
+on:
+  workflow_dispatch:
+    inputs:
+      release_ref:
+        description: Git ref to tag
+        required: true
+        default: main
+
+permissions:
+  contents: write
+
+env:
+  git_user_name: localstack[bot]
+  git_user_email: localstack-bot@users.noreply.github.com
+
+concurrency:
+  group: create-release-tag
+  cancel-in-progress: false
+
+jobs:
+  create-tag:
+    name: Create next CalVer tag
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.release_ref }}
+          fetch-depth: 0
+
+      - name: Configure Git user
+        env:
+          GIT_USER_NAME: ${{ env.git_user_name }}
+          GIT_USER_EMAIL: ${{ env.git_user_email }}
+        run: |
+          git config user.name "${GIT_USER_NAME}"
+          git config user.email "${GIT_USER_EMAIL}"
+
+      - name: Fetch tags
+        run: git fetch --tags --force
+
+      - name: Compute next CalVer tag
+        id: next_tag
+        run: |
+          set -euo pipefail
+          year="$(date -u +%Y)"
+          month="$(date -u +%-m)"
+          prefix="${year}.${month}."
+
+          latest="$(git tag --list "${prefix}*" --sort=-v:refname | grep -E "^${year}\.${month}\.[0-9]+$" | head -n 1 || true)"
+          if [[ -z "${latest}" ]]; then
+            patch=0
+          else
+            patch="$(( ${latest##*.} + 1 ))"
+          fi
+
+          tag="${year}.${month}.${patch}"
+          if git rev-parse -q --verify "refs/tags/${tag}" >/dev/null; then
+            echo "Tag ${tag} already exists"
+            exit 1
+          fi
+
+          echo "tag=${tag}" >> "${GITHUB_OUTPUT}"
+
+      - name: Create and push tag
+        run: |
+          tag="${{ steps.next_tag.outputs.tag }}"
+          git tag -a "${tag}" -m "Release ${tag}"
+          git push origin "${tag}"
+
+      - name: Print created tag
+        run: echo "Created tag ${{ steps.next_tag.outputs.tag }}"

.gitignore

@@ -1,4 +1,5 @@
 bin/
+dist/
 *.test
 
-.idea
+.idea

.goreleaser.yaml

@@ -0,0 +1,39 @@
+version: 2
+
+project_name: lstk
+
+builds:
+  - id: lstk
+    main: ./main.go
+    binary: lstk
+    env:
+      - CGO_ENABLED=0
+    goos:
+      - linux
+      - darwin
+      - windows
+    goarch:
+      - amd64
+      - arm64
+    flags:
+      - -trimpath
+    ldflags:
+      - -s -w -X github.com/localstack/lstk/cmd.version={{ .Version }} -X github.com/localstack/lstk/cmd.commit={{ .Commit }} -X github.com/localstack/lstk/cmd.buildDate={{ .Date }}
+
+archives:
+  - id: lstk
+    ids:
+      - lstk
+    name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}"
+    formats:
+      - tar.gz
+    format_overrides:
+      - goos: windows
+        formats:
+          - zip
+
+checksum:
+  name_template: checksums.txt
+
+changelog:
+  use: github-native

README.md

@@ -1,2 +1,63 @@
 # lstk
-Localstack's new CLI 🌟 (v2) 
+Localstack's new CLI (v2).
+
+## Versioning
+`lstk` uses calendar versioning in a SemVer-compatible format:
+
+- `YYYY.M.patch`
+- Example (current format): `2026.2.0`
+
+Release tags are the source of truth for published versions.
+
+## Version Output
+The CLI exposes version info through:
+
+- `lstk version`
+- `lstk --version`
+
+Output format:
+
+- `lstk <version> (<commit>, <buildDate>)`
+
+At local development time (without ldflags), defaults are:
+
+- `version=dev`
+- `commit=none`
+- `buildDate=unknown`
+
+## Releasing with GoReleaser
+Release automation uses the CI workflow plus one helper workflow:
+
+1. `Create Release Tag` (`.github/workflows/create-release-tag.yml`)
+2. `LSTK CI` (`.github/workflows/ci.yml`)
+
+How it works:
+
+1. Manually run `Create Release Tag` from GitHub Actions (default ref: `main`).
+2. The workflow computes and pushes the next CalVer tag for the current UTC month.
+3. Pushing that tag triggers `LSTK CI`.
+4. In `LSTK CI`, the `release` job runs only for tag refs and publishes the GitHub release with GoReleaser.
+
+## Published Artifacts
+Each release publishes binaries for:
+
+- `linux/amd64`
+- `linux/arm64`
+- `darwin/amd64`
+- `darwin/arm64`
+- `windows/amd64`
+- `windows/arm64`
+
+Archive formats:
+
+- `tar.gz` for Linux and macOS
+- `zip` for Windows
+
+Each release also includes `checksums.txt`.
+
+## Local Dry Run
+To validate release packaging locally without publishing:
+
+```bash
+goreleaser release --snapshot --clean
+```

cmd/root.go

@@ -13,11 +13,19 @@ import (
 	"github.com/spf13/cobra"
 )
 
+var version = "dev"
+var commit = "none"
+var buildDate = "unknown"
+
 var rootCmd = &cobra.Command{
 	Use:   "lstk",
 	Short: "LocalStack CLI",
 	Long:  "lstk is the command-line interface for LocalStack.",
 	PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
+		// Version should be side-effect free and must not create/read user config.
+		if cmd.Name() == "version" {
+			return nil
+		}
 		return config.Init()
 	},
 	Run: func(cmd *cobra.Command, args []string) {
@@ -35,6 +43,8 @@ var rootCmd = &cobra.Command{
 }
 
 func init() {
+	rootCmd.Version = version
+	rootCmd.SetVersionTemplate(versionLine() + "\n")
 	rootCmd.AddCommand(startCmd)
 }
 

cmd/version.go

@@ -0,0 +1,25 @@
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+)
+
+var versionCmd = &cobra.Command{
+	Use:   "version",
+	Short: "Print the lstk version",
+	Long:  "Print version information for the lstk binary.",
+	RunE: func(cmd *cobra.Command, args []string) error {
+		_, err := fmt.Fprintln(cmd.OutOrStdout(), versionLine())
+		return err
+	},
+}
+
+func init() {
+	rootCmd.AddCommand(versionCmd)
+}
+
+func versionLine() string {
+	return fmt.Sprintf("lstk %s (%s, %s)", version, commit, buildDate)
+}

cmd/version_test.go

@@ -0,0 +1,24 @@
+package cmd
+
+import "testing"
+
+func TestVersionLine(t *testing.T) {
+	originalVersion := version
+	originalCommit := commit
+	originalBuildDate := buildDate
+	t.Cleanup(func() {
+		version = originalVersion
+		commit = originalCommit
+		buildDate = originalBuildDate
+	})
+
+	version = "2026.2.0"
+	commit = "abc1234"
+	buildDate = "2026-02-17T15:04:05Z"
+
+	got := versionLine()
+	want := "lstk 2026.2.0 (abc1234, 2026-02-17T15:04:05Z)"
+	if got != want {
+		t.Fatalf("versionLine() = %q, want %q", got, want)
+	}
+}