chore: automation for docs pre-release (opendatahub-io#563)

jland-redhat · web-flow · commit 409b0a72f8aa · 2026-03-31T19:49:00.000Z
Basically this pr just adds the ability to update with a new release
without updating the `latest` alias. Meaning we can cut docs for 3.4 but
still have 3.3 be our default for now.

&lt;!-- This is an auto-generated comment: release notes by coderabbit.ai
--&gt;
## Summary by CodeRabbit

* **New Features**
* Added a prerelease option to control release vs. prerelease status and
adjust docs deployment behavior.
* Added a manual workflow to promote an existing release tag and update
the docs "latest" alias.

* **Chores**
* Release workflow updated to respect prerelease semantics when
publishing releases and docs.
* Pinned documentation syntax-highlighting dependency to a safe version
range.
&lt;!-- end of auto-generated comment: release notes by coderabbit.ai --&gt;
diff --git a/.github/workflows/create-release.yml b/.github/workflows/create-release.yml
@@ -10,8 +10,9 @@
 # Usage:
 #   1. Go to Actions > Create Release > Run workflow
 #   2. Enter the tag (e.g., v1.0.0)
-#   3. Optionally enable "Allow overwriting existing tag" (only for pre-release iterations)
-#   4. Optionally enable "Create GitHub release"
+#   3. Optionally enable "Pre-release" to skip updating the docs 'latest' alias
+#   4. Optionally enable "Allow overwriting existing tag" (only for pre-release iterations)
+#   5. Optionally enable "Create GitHub release"
 #
 # The workflow will:
 #   - Extract minor version (e.g., v1.0.0 -> v1.x)
@@ -30,6 +31,11 @@ on:
         description: 'Release tag (e.g., v1.0.0)'
         required: true
         type: string
+      prerelease:
+        description: 'Pre-release (will not update the docs "latest" alias)'
+        required: false
+        type: boolean
+        default: false
       allow_tag_overwrite:
         description: 'Allow overwriting existing tag (use only for pre-release iterations)'
         required: false
@@ -58,7 +64,8 @@ jobs:
       version_tag: ${{ steps.set_vars.outputs.version_tag }}
       minor_release_branch: ${{ steps.set_vars.outputs.minor_release_branch }}
       minor_version: ${{ steps.set_vars.outputs.minor_version }}
-    
+      is_prerelease: ${{ steps.prerelease.outputs.is_prerelease }}
+
     steps:
       - name: Checkout code
         uses: actions/checkout@v6
@@ -95,6 +102,11 @@ jobs:
           echo "Minor version: $MINOR_VERSION"
           echo "Release branch: $MINOR_BRANCH"
 
+      - name: Set unified prerelease flag
+        id: prerelease
+        run: |
+          echo "is_prerelease=${{ inputs.prerelease || contains(inputs.tag, '-') || contains(inputs.tag, 'alpha') || contains(inputs.tag, 'beta') || contains(inputs.tag, 'rc') }}" >> "$GITHUB_OUTPUT"
+
       - name: Validate tag format
         run: |
           TAG="${{ inputs.tag }}"
@@ -110,6 +122,7 @@ jobs:
     outputs:
       version_tag: ${{ needs.prepare-release.outputs.version_tag }}
       minor_release_branch: ${{ needs.prepare-release.outputs.minor_release_branch }}
+      is_prerelease: ${{ needs.prepare-release.outputs.is_prerelease }}
     
     steps:
       - name: Checkout code
@@ -176,6 +189,7 @@ jobs:
     needs: create-release-branch
     outputs:
       version_tag: ${{ needs.create-release-branch.outputs.version_tag }}
+      is_prerelease: ${{ needs.create-release-branch.outputs.is_prerelease }}
     
     steps:
       - name: Checkout release branch
@@ -191,13 +205,15 @@ jobs:
           git config user.email "${{ env.GH_USER_EMAIL }}"
 
       - name: Create and push git tag
+        env:
+          ALLOW_TAG_OVERWRITE: ${{ inputs.allow_tag_overwrite }}
         run: |
           TAG="${{ needs.create-release-branch.outputs.version_tag }}"
           BRANCH="${{ needs.create-release-branch.outputs.minor_release_branch }}"
           
           # Check if tag already exists
           if git rev-parse "$TAG" >/dev/null 2>&1; then
-            if [ "${{ inputs.allow_tag_overwrite }}" != "true" ]; then
+            if [ "$ALLOW_TAG_OVERWRITE" != "true" ]; then
               echo "❌ Error: Tag $TAG already exists!"
               echo ""
               echo "Tags should be immutable once released. To overwrite an existing tag:"
@@ -241,7 +257,7 @@ jobs:
             
             > Note: Release notes can be edited after creation.
           draft: false
-          prerelease: ${{ contains(inputs.tag, '-') || contains(inputs.tag, 'alpha') || contains(inputs.tag, 'beta') || contains(inputs.tag, 'rc') }}
+          prerelease: ${{ needs.create-release-branch.outputs.is_prerelease == 'true' }}
 
   build-and-push-image:
     name: Build and Push Image
@@ -278,22 +294,26 @@ jobs:
         id: build_image
         env:
           QUAY_REPO: ${{ secrets.APP_QUAY_REPO }}
+          VERSION_TAG: ${{ needs.create-tag.outputs.version_tag }}
         run: |
           if [ -n "$QUAY_REPO" ]; then
             echo "Using custom repository from secret: $QUAY_REPO"
             echo "repo=$QUAY_REPO" >> $GITHUB_OUTPUT
-            make build-push-image REPO="$QUAY_REPO" TAG=${{ needs.create-tag.outputs.version_tag }} CONTAINER_ENGINE=docker
+            make build-push-image REPO="$QUAY_REPO" TAG="$VERSION_TAG" CONTAINER_ENGINE=docker
           else
             echo "Using Makefile default repository: quay.io/opendatahub/maas-api"
             echo "repo=quay.io/opendatahub/maas-api" >> $GITHUB_OUTPUT
-            make build-push-image TAG=${{ needs.create-tag.outputs.version_tag }} CONTAINER_ENGINE=docker
+            make build-push-image TAG="$VERSION_TAG" CONTAINER_ENGINE=docker
           fi
 
   deploy-documentation:
     name: Deploy Documentation
     runs-on: ubuntu-latest
     needs: create-tag
-    
+    concurrency:
+      group: pages
+      cancel-in-progress: false
+
     steps:
       - name: Checkout version tag
         uses: actions/checkout@v6
@@ -326,13 +346,18 @@ jobs:
           git config --global user.email "${{ env.GH_USER_EMAIL }}"
 
       - name: Deploy versioned docs with mike
+        env:
+          PRERELEASE: ${{ needs.create-tag.outputs.is_prerelease }}
+          VERSION_TAG: ${{ needs.create-tag.outputs.version_tag }}
         run: |
           cd docs
-          # Deploy the new version and update latest
-          # Note: mike will automatically create the gh-pages branch if it doesn't exist
-          mike deploy --push --update-aliases ${{ needs.create-tag.outputs.version_tag }} latest
-          # Set latest as the default version
-          mike set-default --push latest
+          if [ "$PRERELEASE" = "true" ]; then
+            echo "Pre-release: deploying docs version without updating 'latest' alias"
+            mike deploy --push "$VERSION_TAG"
+          else
+            mike deploy --push --update-aliases "$VERSION_TAG" latest
+            mike set-default --push latest
+          fi
 
   summary:
     name: Release Summary
@@ -342,27 +367,37 @@ jobs:
     
     steps:
       - name: Summary
+        env:
+          VERSION_TAG: ${{ needs.create-tag.outputs.version_tag }}
+          MINOR_BRANCH: ${{ needs.create-release-branch.outputs.minor_release_branch }}
+          IMAGE_REPO: ${{ needs.build-and-push-image.outputs.image_repo }}
+          IS_PRERELEASE: ${{ needs.prepare-release.outputs.is_prerelease }}
+          CREATE_RELEASE: ${{ inputs.create_release }}
         run: |
           {
             echo "## Release Summary"
             echo ""
-            echo "✅ **Tag**: \`${{ needs.create-tag.outputs.version_tag }}\`"
-            echo "✅ **Release Branch**: \`${{ needs.create-release-branch.outputs.minor_release_branch }}\`"
+            echo "✅ **Tag**: \`$VERSION_TAG\`"
+            echo "✅ **Release Branch**: \`$MINOR_BRANCH\`"
             echo "✅ **Git Tag**: Created and pushed from release branch"
-            echo "✅ **Image Built & Pushed**: \`${{ needs.build-and-push-image.outputs.image_repo }}:${{ needs.create-tag.outputs.version_tag }}\`"
-            echo "✅ **Documentation Deployed**: \`${{ needs.create-tag.outputs.version_tag }}\`"
-            if [ "${{ inputs.create_release }}" == "true" ]; then
+            echo "✅ **Image Built & Pushed**: \`$IMAGE_REPO:$VERSION_TAG\`"
+            echo "✅ **Documentation Deployed**: \`$VERSION_TAG\`"
+            if [ "$CREATE_RELEASE" = "true" ]; then
               echo "✅ **GitHub Release**: Created"
             fi
             echo ""
             echo "### Updated Files"
             echo "- \`deployment/base/maas-api/kustomization.yaml\`"
             echo "- \`maas-api/deploy/overlays/dev/kustomization.yaml\`"
             echo "- \`maas-api/deploy/overlays/odh/params.env\`"
-            echo "- MAAS_REF references updated to use \`${{ needs.create-tag.outputs.version_tag }}\`"
+            echo "- MAAS_REF references updated to use \`$VERSION_TAG\`"
             echo ""
             echo "### Documentation"
-            echo "- Docs Version: \`${{ needs.create-tag.outputs.version_tag }}\`"
-            echo "- Docs Alias: \`latest\`"
+            echo "- Docs Version: \`$VERSION_TAG\`"
+            if [ "$IS_PRERELEASE" = "true" ]; then
+              echo "- Docs Alias: _(not updated — pre-release)_"
+            else
+              echo "- Docs Alias: \`latest\`"
+            fi
             echo "- Docs URL: https://opendatahub-io.github.io/models-as-a-service/"
           } >> "$GITHUB_STEP_SUMMARY"
diff --git a/.github/workflows/maas-api-ci.yml b/.github/workflows/maas-api-ci.yml
@@ -69,17 +69,3 @@ jobs:
 
       - name: Build image
         run: make build-image
-      
-      - name: Login to Quay.io
-        if: github.event_name == 'push'
-        uses: docker/login-action@v3
-        with:
-          registry: quay.io
-          username: ${{ secrets.APP_QUAY_USERNAME }}
-          password: ${{ secrets.APP_QUAY_TOKEN }}
-      
-      - name: Push image to Quay.io
-        if: github.event_name == 'push'
-        run: | 
-          make build-push-image
-          make build-push-image -e TAG=${{ github.sha }}
diff --git a/.github/workflows/update-docs-latest.yml b/.github/workflows/update-docs-latest.yml
@@ -0,0 +1,98 @@
+# Update Docs Latest Alias
+#
+# Updates the docs "latest" alias to point to an existing release tag.
+# The tag must already exist in the repository.
+#
+# Usage:
+#   1. Go to Actions > Update Docs Latest > Run workflow
+#   2. Enter the existing tag to promote to "latest" (e.g., v1.2.0)
+
+name: Update Docs Latest
+run-name: Update Docs Latest → ${{ inputs.tag }}
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Existing release tag to set as "latest" (e.g., v1.2.0)'
+        required: true
+        type: string
+
+env:
+  GH_USER_NAME: github-actions[bot]
+  GH_USER_EMAIL: github-actions[bot]@users.noreply.github.com
+
+jobs:
+  update-latest:
+    name: Update Latest Alias
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    concurrency:
+      group: pages
+      cancel-in-progress: false
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Validate tag exists
+        env:
+          TAG: ${{ inputs.tag }}
+        run: |
+          if ! git rev-parse -- "$TAG" >/dev/null 2>&1; then
+            echo "❌ Error: Tag '$TAG' does not exist."
+            echo "This workflow requires an existing tag. Create a release first."
+            exit 1
+          fi
+          echo "✅ Tag '$TAG' found at $(git rev-parse -- "$TAG")"
+
+      - name: Checkout tag
+        env:
+          TAG: ${{ inputs.tag }}
+        run: git checkout --detach -- "$TAG"
+
+      - name: Setup Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: '3.11'
+
+      - name: Cache pip dependencies
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('docs/requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install dependencies
+        run: pip install -r docs/requirements.txt
+
+      - name: Configure Git
+        run: |
+          git config --global user.name "${{ env.GH_USER_NAME }}"
+          git config --global user.email "${{ env.GH_USER_EMAIL }}"
+
+      - name: Update latest alias
+        env:
+          TAG: ${{ inputs.tag }}
+        run: |
+          cd docs
+          mike deploy --push --update-aliases "$TAG" latest
+          mike set-default --push latest
+
+      - name: Summary
+        env:
+          TAG: ${{ inputs.tag }}
+        run: |
+          {
+            echo "## Docs Latest Updated"
+            echo ""
+            echo "✅ **\`latest\`** alias now points to **\`$TAG\`**"
+            echo ""
+            echo "- Docs URL: https://opendatahub-io.github.io/models-as-a-service/"
+          } >> "$GITHUB_STEP_SUMMARY"
diff --git a/docs/README.md b/docs/README.md
@@ -178,4 +178,4 @@ When a new release tag is created using the `create-release.yml` workflow, the f
    - For production deployments, use a release tag: `export MAAS_REF="v1.0.0"`
    - For development/testing, use: `export MAAS_REF="main"`
 
-This ensures that documentation and deployment scripts always reference stable release tags rather than the moving `main` branch.
+This ensures that documentation and deployment scripts always reference stable release tags rather than the moving `main` branch. 
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,5 +1,7 @@
 mkdocs>=1.5.0,<2.0
 mkdocs-material>=9.0.0
+# Pygments 2.20 html-escapes filename; pymdownx passes filename=None for untitled blocks → AttributeError in mkdocs build
+pygments>=2.12,<2.20
 mkdocs-git-revision-date-localized-plugin>=1.2.0
 mkdocs-swagger-ui-tag>=0.7.0
 mike>=2.0.0
