From 382eeb433ae73423cce41e0a50a28662e562e20c Mon Sep 17 00:00:00 2001
From: gongzhongqiang <gongzhongqiang@apache.org>
Date: Fri, 9 Oct 2026 15:46:56 +0800
Subject: [PATCH] ci(docs): fix gh-pages deploy race and align docs workflows
 with Apache practice

The docs deploy workflow ran on every push to main and each run takes
about 30 minutes (full-history checkout plus Docusaurus build), so
bursts of merges race their final 'git push --force gh-pages'. On
2026-10-08 the deploy triggered by the Java-only commit a559aa1a
failed with "cannot lock ref 'refs/heads/gh-pages'" because a
concurrent deploy recreated the branch seconds earlier (run
37812706645).

- deploy-docs.yml: trigger only on website/** and .asf.yaml changes so
  Java-only merges no longer deploy; queue deploys through a
  non-cancelling concurrency group instead of racing; add
  workflow_dispatch for manual redeploys; cache the pnpm store.
- ci-docs/preview-docs/deploy-docs: least-privilege permissions
  (write only where needed), persist-credentials: false on checkout,
  each workflow file added to its own path filter, and unified
  'Docs <role>' naming, following common Apache practice (iceberg,
  superset).

Signed-off-by: gongzhongqiang <gongzhongqiang@apache.org>
---
 .github/workflows/ci-docs.yml      |  8 +++++++-
 .github/workflows/deploy-docs.yml  | 19 ++++++++++++++++++-
 .github/workflows/preview-docs.yml | 13 ++++++++++++-
 3 files changed, 37 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/ci-docs.yml b/.github/workflows/ci-docs.yml
index afc2be6c1..bedb15f2c 100644
--- a/.github/workflows/ci-docs.yml
+++ b/.github/workflows/ci-docs.yml
@@ -15,12 +15,16 @@
 # specific language governing permissions and limitations
 # under the License.
 
-name: Documentation CI
+name: Docs CI
 
 on:
   pull_request:
     paths:
       - 'website/**'
+      - '.github/workflows/ci-docs.yml'
+
+permissions:
+  contents: read
 
 concurrency:
   group: ci-docs-${{ github.event.pull_request.number || github.ref }}
@@ -32,6 +36,8 @@ jobs:
     steps:
       - name: Checkout code
         uses: actions/checkout@v7
+        with:
+          persist-credentials: false
 
       - name: Setup pnpm
         uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86
diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
index 4d317d896..fd48978fb 100644
--- a/.github/workflows/deploy-docs.yml
+++ b/.github/workflows/deploy-docs.yml
@@ -15,20 +15,35 @@
 # specific language governing permissions and limitations
 # under the License.
 
-name: Deploy Docusaurus to GitHub Pages
+name: Docs Deploy
 
 on:
   push:
     branches: [ main ]
+    paths:
+      - 'website/**'
+      - '.asf.yaml'
+      - '.github/workflows/deploy-docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: deploy-docs
+  cancel-in-progress: false
 
 jobs:
   deploy:
     if: github.repository == 'apache/fesod'
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
     steps:
       - uses: actions/checkout@v7
         with:
           fetch-depth: 0
+          persist-credentials: false
 
       - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86
         with:
@@ -38,6 +53,8 @@ jobs:
       - uses: actions/setup-node@v7
         with:
           node-version: "24"
+          cache: pnpm
+          cache-dependency-path: website/pnpm-lock.yaml
 
       - name: Corepack
         working-directory: website
diff --git a/.github/workflows/preview-docs.yml b/.github/workflows/preview-docs.yml
index 372ee65d6..66302c49c 100644
--- a/.github/workflows/preview-docs.yml
+++ b/.github/workflows/preview-docs.yml
@@ -15,12 +15,21 @@
 # specific language governing permissions and limitations
 # under the License.
 
-name: Preview Documentation
+name: Docs Preview
 
 on:
   pull_request:
     paths:
       - 'website/**'
+      - '.github/workflows/preview-docs.yml'
+
+permissions:
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: preview-docs-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
 
 jobs:
   deploy-preview:
@@ -28,6 +37,8 @@ jobs:
     steps:
       - name: Checkout code
         uses: actions/checkout@v7
+        with:
+          persist-credentials: false
 
       - name: Setup pnpm
         uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86