ci(docs): fix gh-pages deploy auth in reusable docs workflow (agntcy#1725)

## Summary
- fixes docs deploy on main where  fails to push gh-pages
- keeps  credential persistence disabled
- adds an ephemeral  setup for deploy modes only, using 

## Why
After PR agntcy#1720, Documentation Deploy fails in and root-file publish is
skipped, so GitHub Pages is not updated.

## Security
- no credentials persisted in checkout config
- token is consumed only during deploy jobs via environment and askpass

---------

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

Author: muscariello

.github/workflows/buf-ci.yaml

@@ -15,6 +15,15 @@ on:
       - "**/LICENSE"
   pull_request:
     types: [opened, synchronize, reopened, labeled, unlabeled]
+    paths:
+      # Keep PR trigger aligned with push trigger to avoid running on docs-only changes.
+      - "**.proto"
+      - "**/buf.yaml"
+      - "**/buf.lock"
+      - "**/buf.md"
+      - "**/README.md"
+      - "**/LICENSE"
+      - ".github/workflows/buf-ci.yaml"
   delete:
 permissions:
   contents: read

.github/workflows/codeql.yml

@@ -9,6 +9,11 @@ on:
     branches: [ "main" ]
   pull_request:
     branches: [ "main" ]
+    paths-ignore:
+      - 'docs/**'
+      - '.github/workflows/docs-ci.yaml'
+      - '.github/workflows/docs-deploy.yml'
+      - '.github/workflows/reusable-docs.yml'
   schedule:
     - cron: '42 5 * * 6'
   workflow_dispatch:

.github/workflows/coverage.yaml

@@ -2,13 +2,18 @@
 # SPDX-License-Identifier: Apache-2.0
 
 ---
-name: ci-publish-prokect-coverage
+name: ci-publish-project-coverage
 
 on:
   push:
     branches: [main]
   pull_request:
     branches: [main]
+    paths-ignore:
+      - 'docs/**'
+      - '.github/workflows/docs-ci.yaml'
+      - '.github/workflows/docs-deploy.yml'
+      - '.github/workflows/reusable-docs.yml'
 
 jobs:
   coverage:

.github/workflows/docs-ci.yaml

@@ -9,8 +9,6 @@ on:
   pull_request:
     paths:
       - 'docs/**'
-      - '.github/workflows/docs-ci.yaml'
-      - '.github/workflows/reusable-docs.yml'
 
 permissions:
   contents: read

.github/workflows/docs-deploy.yml

@@ -16,8 +16,6 @@ on:
     branches: [main]
     paths:
       - 'docs/**'
-      - '.github/workflows/docs-deploy.yml'
-      - '.github/workflows/reusable-docs.yml'
     tags:
       - 'v*.*.*'
   release:

.github/workflows/reusable-docs.yml

@@ -38,7 +38,8 @@ jobs:
         with:
           # mike needs full history and the gh-pages branch to deploy versions.
           fetch-depth: 0
-          persist-credentials: false
+          # Keep checkout credentials for mike --push in deploy modes.
+          persist-credentials: true
 
       - name: Setup uv
         uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2