Version the actions: semver tags + v1 alias, deprecate ftf action, bump managed actions

- Add release.yml: pushing a vX.Y.Z tag moves the major alias tag (v1) and
  creates the GitHub release; consumers pin module-ci-action@v1 instead of
  @master.
- Document the versioning convention in the root and module-ci-action READMEs;
  example workflows now reference @v1.
- Mark the ftf-based module-preview-action as deprecated (root README +
  its own README); module-ci-action is the current action.
- Bump managed actions: actions/checkout v4 -> v7 (action steps, test
  workflows, README examples), actions/setup-python v5 -> v6.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: anujhydrabadi

.github/workflows/release.yml

@@ -0,0 +1,53 @@
+name: "Release"
+
+# Versioning for the actions in this repo (they are consumed as
+# Facets-cloud/github-actions/<action>@<ref>):
+#
+#   - Exact releases are annotated semver tags: v1.0.0, v1.1.0, ...
+#   - Each major has a MOVING alias tag (v1, v2, ...) that always points at the
+#     latest release of that major — the same convention as actions/checkout.
+#     Consumers (including the workflow the control plane bootstraps into
+#     customer repos) pin the alias: module-ci-action@v1.
+#
+# Pushing a semver tag runs this workflow, which force-moves the major alias
+# to the new tag and creates a GitHub release for it. To cut a release:
+#
+#   git tag v1.2.0 && git push origin v1.2.0
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Move the major alias tag
+        run: |
+          set -euo pipefail
+          TAG="${GITHUB_REF_NAME}"
+          MAJOR="${TAG%%.*}"   # v1.2.3 -> v1
+          echo "Pointing ${MAJOR} at ${TAG}"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -f -a "${MAJOR}" -m "Point ${MAJOR} at ${TAG}" "${TAG}^{}"
+          git push origin "${MAJOR}" --force
+
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          TAG="${GITHUB_REF_NAME}"
+          if gh release view "${TAG}" --repo "${GITHUB_REPOSITORY}" >/dev/null 2>&1; then
+            echo "Release ${TAG} already exists; skipping."
+          else
+            gh release create "${TAG}" --repo "${GITHUB_REPOSITORY}" \
+              --title "${TAG}" --generate-notes
+          fi

.github/workflows/test-module-ci.yaml

@@ -20,7 +20,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout Repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Install shellcheck
         run: sudo apt-get update && sudo apt-get install -y shellcheck

.github/workflows/test-module-preview.yaml

@@ -16,7 +16,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout Repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Run Facets Module Preview Action (Local)
         uses: ./module-preview-action  # Run from local repo

README.md

@@ -1,19 +1,10 @@
 # Facets GitHub Actions
 
+Actions in this repo are consumed as `Facets-cloud/github-actions/<action>@<version>`.
+Releases are semver tags with a moving major alias (`v1` always points at the latest
+`v1.x.y`) — pin the major alias unless you need an exact version.
 
-## 1. Facets Module Preview & Security Scan
-
-The **Facets Module Preview & Security Scan** GitHub Action automates validation and security checks for Facets
-Terraform modules. It performs the following tasks:
-
-[module-preview-action README](./module-preview-action/README.md).
-
-- **Terraform Formatting Checks**: Ensures Terraform files are formatted correctly.
-- **Terraform Validation**: Verifies the correctness of Terraform configurations.
-- **Checkov Security Scanning**: Identifies security vulnerabilities in Terraform code.
-- **Facets Module Preview**: Registers a Preview only module with your Facets Control Plane.
-
-## 2. Facets Module CI
+## 1. Facets Module CI (current)
 
 The **Facets Module CI** GitHub Action provides end-to-end CI for a Facets **modules
 repository** (`modules/{intent}/{flavor}/{version}`) using the **`raptor`** CLI. It runs
@@ -28,6 +19,23 @@ in three modes, derived automatically from the triggering event:
 - **Cleanup (on pull request close)**: Deletes each changed module's preview, but only
   the previews this PR's own commits created (ownership-checked).
 
-This action is a sibling of the `ftf`-based `module-preview-action` above and does not
-replace it — choose the one matching your CLI.
+This is the action the Facets control plane wires into bootstrapped modules
+repositories, and the recommended CI for all modules repos.
 
+## 2. Facets Module Preview & Security Scan (deprecated)
+
+> ⚠️ **Deprecated.** This action is based on the legacy `ftf` CLI and is kept only for
+> existing workflows that still use it. It receives no new features. New repos should
+> use [**module-ci-action**](./module-ci-action/README.md) above; to migrate, replace
+> the `module-preview-action` step with `module-ci-action` (raptor-based inputs — see
+> its README) and adopt the `modules/{intent}/{flavor}/{version}` layout.
+
+The **Facets Module Preview & Security Scan** GitHub Action automates validation and
+security checks for Facets Terraform modules:
+
+[module-preview-action README](./module-preview-action/README.md).
+
+- **Terraform Formatting Checks**: Ensures Terraform files are formatted correctly.
+- **Terraform Validation**: Verifies the correctness of Terraform configurations.
+- **Checkov Security Scanning**: Identifies security vulnerabilities in Terraform code.
+- **Facets Module Preview**: Registers a Preview only module with your Facets Control Plane.

module-ci-action/README.md

@@ -14,8 +14,9 @@ triggering event:
 | `pull_request` **closed without merge** | **cleanup** | Deletes the preview each changed module owns — **only if** the preview belongs to a commit from this PR. |
 | `pull_request` **closed by merge** | **no-op** | Skipped: the concurrent `push` (publish) run re-uploads and publishes the module at the merge commit, so it owns the slot. Running cleanup here would be redundant and could race the publish. |
 
-> This action is a sibling of [`module-preview-action`](../module-preview-action)
-> (the `ftf`-based action). They are independent — pick the one that matches your CLI.
+> This action supersedes the **deprecated** `ftf`-based
+> [`module-preview-action`](../module-preview-action), which is kept only for
+> existing workflows.
 
 ## Modules-repo layout
 
@@ -117,7 +118,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Facets Module CI
-        uses: Facets-cloud/github-actions/module-ci-action@master
+        uses: Facets-cloud/github-actions/module-ci-action@v1
         with:
           control_plane_url: ${{ secrets.CONTROL_PLANE_URL }}
           username: ${{ secrets.FACETS_USERNAME }}
@@ -130,6 +131,19 @@ jobs:
 If you prefer separate workflow files, split the three triggers apart and let `mode`
 stay `auto`; the action derives `preview` / `publish` / `cleanup` from each event.
 
+## Versioning
+
+Reference this action by version, not by branch:
+
+- **`@v1`** — the moving major alias; always points at the latest `v1.x.y` release.
+  This is what the control plane's bootstrapped workflow uses and the right default.
+- **`@v1.2.3`** — an exact release, if you need to pin harder.
+
+Releases are cut by pushing a semver tag (`git tag v1.2.0 && git push origin v1.2.0`);
+the repo's `release.yml` workflow then moves the major alias and publishes the GitHub
+release. Breaking changes to the action's inputs or behavior get a new major
+(`v2`, with a `v2` alias) — the `v1` alias never picks them up.
+
 ## Single-preview-slot semantics
 
 Each module (`intent/flavor/version`) has exactly **one preview slot** on the Control

module-ci-action/action.yml

@@ -49,7 +49,7 @@ runs:
   using: "composite"
   steps:
     - name: Checkout repository
-      uses: actions/checkout@v4
+      uses: actions/checkout@v7
       with:
         fetch-depth: 0
 

module-preview-action/README.md

@@ -1,5 +1,10 @@
 # Facets Preview & Security Scan GitHub Action
 
+> ⚠️ **Deprecated.** This action is based on the legacy `ftf` CLI and is kept only for
+> existing workflows. It receives no new features. Use
+> [**module-ci-action**](../module-ci-action/README.md) instead — the `raptor`-based
+> action the Facets control plane wires into bootstrapped modules repositories.
+
 This GitHub Action performs:
 
 ✅ Terraform formatting checks  
@@ -43,7 +48,7 @@ jobs:
 
     steps:
       - name: Checkout Repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Run Facets Preview & Security Scan
         uses: Facets-cloud/github-actions/module-preview-action@master

module-preview-action/action.yml

@@ -45,7 +45,7 @@ runs:
   using: "composite"
   steps:
     - name: Checkout Repository
-      uses: actions/checkout@v4
+      uses: actions/checkout@v7
       with:
         fetch-depth: 0
 
@@ -55,7 +55,7 @@ runs:
       run: |
           touch ./requirements.txt
 
-    - uses: actions/setup-python@v5
+    - uses: actions/setup-python@v6
       with:
         python-version: "3.12"
         cache: "pip"