ci(docs): automate documentation sync and add build validation (cloudnative-pg#10296)

Automatically trigger documentation sync to the docs repository on
release tag pushes and when docs/src/ changes are merged to main. Add a
CI job that builds the Docusaurus site to catch documentation errors
before merging.

Closes cloudnative-pg#10295

---------

Signed-off-by: Marco Nenciarini <marco.nenciarini@enterprisedb.com>
(cherry picked from commit a869c82)

Author: mnencia

.github/workflows/continuous-integration.yml

@@ -345,6 +345,26 @@ jobs:
             exit 1
           fi
 
+  docs-build:
+    name: Verify documentation builds
+    needs:
+      - duplicate_runs
+      - change-triage
+    if: |
+      needs.duplicate_runs.outputs.should_skip != 'true' &&
+      needs.change-triage.outputs.docs-changed == 'true'
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+
+      - name: Build documentation
+        run: |
+          docker run --rm \
+            -v ./docs/src:/website/docs \
+            ghcr.io/cloudnative-pg/docs:latest \
+            yarn build
+
   crd:
     name: Verify CRD is up to date
     needs:

.github/workflows/sync-docs.yml

@@ -1,6 +1,13 @@
 name: Sync Docs
 
 on:
+  push:
+    tags:
+      - v*
+    branches:
+      - main
+    paths:
+      - 'docs/src/**'
   workflow_dispatch:
     inputs:
       version:
@@ -11,7 +18,36 @@ on:
 permissions: {}
 
 jobs:
-  dispatch:
+  dispatch-tag:
+    if: >-
+      github.repository_owner == 'cloudnative-pg' &&
+      startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Dispatch Docs Repository Workflow
+        uses: peter-evans/repository-dispatch@28959ce8df70de7be546dd1250a005dd32156697 # v4
+        with:
+          repository: cloudnative-pg/docs
+          token: ${{ secrets.REPO_GHA_PAT }}
+          event-type: cnpg-docs-release
+          client-payload: ${{ format('{{"tag":{0}}}', toJSON(github.ref_name)) }}
+
+  dispatch-main:
+    if: >-
+      github.repository_owner == 'cloudnative-pg' &&
+      !startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Dispatch Docs Repository Workflow
+        uses: peter-evans/repository-dispatch@28959ce8df70de7be546dd1250a005dd32156697 # v4
+        with:
+          repository: cloudnative-pg/docs
+          token: ${{ secrets.REPO_GHA_PAT }}
+          event-type: cnpg-docs-release
+          client-payload: '{"tag":"main"}'
+
+  dispatch-manual:
+    if: github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
     steps:
       - name: Dispatch Docs Repository Workflow