ci: publish docs only on manual trigger and release (#8502)

* feat: move docs build output to docs branch instead of committing to master

Agent-Logs-Url: https://github.com/pubkey/rxdb/sessions/ed54ade7-5c8f-47ca-8752-60fbeabb1bbd

Co-authored-by: pubkey <8926560+pubkey@users.noreply.github.com>

* chore: clarify git fetch error suppression comment in build workflow

Agent-Logs-Url: https://github.com/pubkey/rxdb/sessions/ed54ade7-5c8f-47ca-8752-60fbeabb1bbd

Co-authored-by: pubkey <8926560+pubkey@users.noreply.github.com>

* ci: publish docs only on manual run and release

Agent-Logs-Url: https://github.com/pubkey/rxdb/sessions/0fd6e292-31df-491e-af39-f322c9b8697b

Co-authored-by: pubkey <8926560+pubkey@users.noreply.github.com>

* docs: align contribute guide with manual/release docs publishing

Agent-Logs-Url: https://github.com/pubkey/rxdb/sessions/0fd6e292-31df-491e-af39-f322c9b8697b

Co-authored-by: pubkey <8926560+pubkey@users.noreply.github.com>

* docs: remove docs publishing note from contribute.md

Agent-Logs-Url: https://github.com/pubkey/rxdb/sessions/d4b1eaa0-3b75-4d39-9035-8433584955c7

Co-authored-by: pubkey <8926560+pubkey@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: pubkey <8926560+pubkey@users.noreply.github.com>

Author: Copilot

.github/workflows/build.yml

@@ -1,22 +1,26 @@
-# This is a basic workflow to help you get started with Actions
+name: Publish Docs
 
-name: build and push
-
-# Controls when the action will run. 
 on:
-  # Allows you to run this workflow manually from the Actions tab
+  # Allow manual triggering from the Actions tab
   workflow_dispatch:
+  # Run automatically when a GitHub release is published
+  release:
+    types: [published]
+
+permissions:
+  contents: write
 
 jobs:
-  # This workflow contains a single job called "build"
-  build-all:
-    # The type of runner that the job will run on
+  publish-docs:
     runs-on: ubuntu-22.04
 
-    # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
-      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
       - uses: actions/checkout@v6
+        with:
+          # Always build docs from the source branch
+          ref: master
+          # Fetch full history so per-file "Last updated" timestamps are accurate
+          fetch-depth: 0
 
       - name: Setup Node.js environment
         uses: actions/setup-node@v6.4.0
@@ -25,28 +29,41 @@ jobs:
 
       - name: install npm dependencies
         run: npm install || (sleep 15 && npm install) || (sleep 15 && npm install)
-      
+
       - name: build code
         run: npm run build
-      
+
+      - name: install docs dependencies
+        run: (cd docs-src && (npm install || (sleep 15 && npm install) || (sleep 15 && npm install)))
+
+      - name: generate headers
+        run: npm run generate:headers
+
       - name: build docs
-        run: |
-          (cd docs-src && (npm install || (sleep 15 && npm install) || (sleep 15 && npm install)))
-          npm run generate:headers
-          npm run docs:build
+        run: npm run docs:build
 
-      - name: Commit files
+      - name: Publish docs to the docs branch
         run: |
-          git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git config --local user.name "github-actions[bot]"
-          git add .
-          git commit -m "BUILD" -a
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git config user.name "github-actions[bot]"
 
-      - name: Push changes
-        uses: ad-m/github-push-action@master
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          branch: ${{ github.ref }}
+          # Try to fetch the existing docs branch; suppress errors because it may not exist yet
+          # on first run (the worktree add --orphan path handles that case).
+          git fetch origin docs:docs 2>/dev/null || true
+          git worktree add /tmp/docs-branch docs 2>/dev/null || \
+            git worktree add --orphan /tmp/docs-branch docs
+
+          # Wipe everything that was previously in the docs branch
+          rm -rf /tmp/docs-branch/*
+
+          # Copy the fresh build output
+          cp -r docs-src/build/. /tmp/docs-branch/
+
+          cd /tmp/docs-branch
+          git add -A
+          # Only commit when something actually changed
+          git diff --cached --quiet || git commit -m "docs: publish from ${{ github.sha }}"
+          git push origin HEAD:docs
 
       - name: notify bing indexnow
         run: npm run docs:notify-indexnow

.github/workflows/cloudflare-pages.yml

@@ -1,6 +1,9 @@
 name: Deploy To Cloudflare Pages
 
 on:
+  # Trigger automatically after docs are published to the docs branch
+  push:
+    branches: [docs]
   workflow_dispatch:
 
 jobs:
@@ -9,9 +12,11 @@ jobs:
     name: Deploy
     steps:
       - uses: actions/checkout@v6
+        with:
+          ref: docs
       - name: Deploy to Cloudflare Pages
         uses: cloudflare/wrangler-action@v3
         with:
           apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
           accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
-          command: pages deploy docs --project-name=rxdb
+          command: pages deploy . --project-name=rxdb

.github/workflows/prevent-commit-to-generated.yml

@@ -5,12 +5,11 @@ on:
   pull_request:
     paths:
     - 'dist/**'
-    - 'docs/**'
 
 jobs:
   warn-user:
     runs-on: ubuntu-22.04
     steps:
       - uses: actions/checkout@v6
       - name: Warn User to not commit generated files
-        run: bash -c 'echo "You have commited generated files (from the dist or docs folder), this is not allowed. You can only commit files that you have manually edited" && exit 1'
+        run: bash -c 'echo "You have commited generated files (from the dist folder), this is not allowed. You can only commit files that you have manually edited" && exit 1'

.gitignore

@@ -30,3 +30,4 @@ plugins/
 ai-context.txt
 ERROR-MESSAGES.md
 .chrome-profile-perf/
+/docs/

docs-src/docs/contribute.md

@@ -54,4 +54,5 @@ To read the docs locally, run `npm run docs:install && npm run docs:serve` and o
 
 
 
+
 # Thank you for contributing!