feat: configuration templates

.github/workflows/cicd.yml

@@ -21,35 +21,18 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  prepare:
-    name: Prepare
-    outputs:
-      release_tag: ${{ steps.vars.outputs.release_tag }}
-    runs-on: ubuntu-latest
-    steps:
-      - name: Resolve required vars
-        id: vars
-        run: |
-          echo "release_tag=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
-
   docs:
     name: Docs
-    needs:
-      - prepare
     uses: ./.github/workflows/reusable-docs.yml
     permissions:
       contents: read
-      pages: write
-      id-token: write
     with:
-      deploy: ${{ startsWith(github.ref, 'refs/tags/') }}
-      version: ${{ needs.prepare.outputs.release_tag }}
+      version: dev
 
   success:
     name: Success
     if: ${{ !cancelled() && !contains(needs.*.result, 'cancelled') && !contains(needs.*.result, 'failure') }}
     needs:
-      - prepare
       - docs
     runs-on: ubuntu-latest
     steps:

.github/workflows/docs-release.yml

@@ -0,0 +1,165 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 Cisco and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Ordered release pipeline (decoupled phases):
+#   1. Build docs — validate MkDocs output
+#   2. Mike — push versioned site to gh-pages (from mkdocs/mike_versions.ini [versions] release)
+#   3. Git tag — create v* tag on the commit that was published
+#   4. Finalize — placeholder / optional GitHub Release (GitHub Pages already serves gh-pages after step 2)
+
+name: Docs release
+
+on:
+  workflow_dispatch:
+    inputs:
+      create_github_release:
+        description: 'After tagging, create a GitHub Release for the same tag'
+        type: choice
+        options:
+          - 'no'
+          - 'yes'
+        default: 'no'
+
+permissions:
+  contents: write
+
+concurrency:
+  group: docs-release
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: '1. Build docs'
+    runs-on: ubuntu-latest
+    env:
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: recursive
+
+      - name: Setup Taskfile
+        shell: bash
+        run: sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin
+
+      - name: Setup UV
+        shell: bash
+        run: curl -LsSf https://astral.sh/uv/install.sh | sh
+
+      - name: Update PATH
+        shell: bash
+        run: echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+
+      - name: Build
+        shell: bash
+        run: |
+          export VERSION="$(cd mkdocs && uv run python mike_version.py release)"
+          task build
+
+  mike:
+    name: '2. Mike (gh-pages)'
+    needs: build
+    runs-on: ubuntu-latest
+    env:
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: recursive
+
+      - name: Setup Taskfile
+        shell: bash
+        run: sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin
+
+      - name: Setup UV
+        shell: bash
+        run: curl -LsSf https://astral.sh/uv/install.sh | sh
+
+      - name: Update PATH
+        shell: bash
+        run: echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+
+      - name: Configure Git for mike
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email github-actions[bot]@users.noreply.github.com
+
+      - name: Fetch gh-pages
+        continue-on-error: true
+        run: git fetch origin gh-pages --depth=1
+
+      - name: Mike deploy
+        shell: bash
+        run: task mike:deploy
+
+  git-tag:
+    name: '3. Git tag'
+    needs: mike
+    runs-on: ubuntu-latest
+    env:
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: recursive
+
+      - name: Setup UV
+        shell: bash
+        run: curl -LsSf https://astral.sh/uv/install.sh | sh
+
+      - name: Update PATH
+        shell: bash
+        run: echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+
+      - name: Create and push tag
+        shell: bash
+        env:
+          TAG_SHA: ${{ github.sha }}
+        run: |
+          set -euo pipefail
+          VER="$(cd mkdocs && uv run python mike_version.py release)"
+          TAG="v${VER}"
+          if git ls-remote --tags origin "refs/tags/${TAG}" | grep -q .; then
+            echo "::error::Tag ${TAG} already exists on origin. Bump [versions] release in mkdocs/mike_versions.ini or delete the remote tag."
+            exit 1
+          fi
+          git tag -a "${TAG}" -m "Documentation release ${TAG}" "${TAG_SHA}"
+          git push origin "${TAG}"
+
+  finalize:
+    name: '4. Deploy / release'
+    needs: git-tag
+    runs-on: ubuntu-latest
+    env:
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup UV
+        shell: bash
+        run: curl -LsSf https://astral.sh/uv/install.sh | sh
+
+      - name: Update PATH
+        shell: bash
+        run: echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+
+      - name: GitHub Release
+        if: ${{ github.event.inputs.create_github_release == 'yes' }}
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          VER="$(cd mkdocs && uv run python mike_version.py release)"
+          TAG="v${VER}"
+          gh release create "${TAG}" --title "Documentation ${TAG}" --notes "Published from workflow [${{ github.run_id }}](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}). Site is served from the gh-pages branch."
+
+      - name: Pages note
+        if: ${{ github.event.inputs.create_github_release != 'yes' }}
+        run: |
+          echo "::notice::GitHub Pages (if configured from gh-pages) is already serving the mike version from step 2. Set **create_github_release** to **yes** to open a GitHub Release on the new tag."

.github/workflows/reusable-docs.yml

@@ -1,60 +1,45 @@
 # SPDX-FileCopyrightText: Copyright (c) 2026 Cisco and/or its affiliates.
 # SPDX-License-Identifier: Apache-2.0
+#
+# Build-only documentation check. Versioned publish (mike), tagging, and releases
+# use .github/workflows/docs-release.yml
 
 name: Documentation
 
 on:
   workflow_call:
     inputs:
-      deploy:
-        description: 'Deploy documentation artifacts'
-        required: true
-        type: boolean
-        default: false
       version:
-        description: 'Version to use for documentation artifacts'
+        description: 'MkDocs macros VERSION (docs_build_version)'
         required: true
         type: string
         default: dev
 
   workflow_dispatch:
     inputs:
-      deploy:
-        description: 'Deploy documentation artifacts'
-        required: true
-        type: boolean
-        default: false
       version:
-        description: 'Version to use for documentation artifacts'
-        required: true
+        description: 'MkDocs macros VERSION'
+        required: false
         type: string
         default: dev
 
 permissions:
   contents: read
-  pages: write
-  id-token: write
 
 jobs:
-  build:
-    name: Build artifacts
+  docs:
+    name: Build docs
     runs-on: ubuntu-latest
+    env:
+      # Use Node 24 for JS-based actions (checkout, etc.); see GitHub deprecation of Node 20 on runners
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
           submodules: 'recursive'
 
-      - name: Setup Pages
-        id: pages
-        uses: actions/configure-pages@v5
-
-      - name: Setup Golang
-        uses: actions/setup-go@v5
-        with:
-          go-version: '1.23.1'
-
       - name: Setup Taskfile
         shell: bash
         run: |
@@ -71,29 +56,7 @@ jobs:
 
       - name: Build docs
         shell: bash
-        env:
-          VERSION: ${{ inputs.version }}
         run: |
+          V="${{ inputs.version }}"
+          export VERSION="${V:-dev}"
           task build
-
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v4
-        with:
-          name: docs-website
-          path: ./.build/site
-
-  deploy:
-    name: Deploy artifacts
-    if: ${{ inputs.deploy == true || inputs.deploy == 'true' }}
-    needs:
-      - build
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    steps:
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4
-        with:
-          artifact_name: docs-website