ci: comprehensive docs-orchestrator audit and fixes

- Add safe.directory + fetch-depth: 0 for container jobs
- Support workflow_dispatch in metadata-regen and deploy-aws
- Guard PR comments against fork PRs
- Add ccache save to pr-metadata-regen
- Use metadata_sync.sh --generate --sync instead of manual steps
- Fix msg_docs source path in metadata_sync.sh
- Guard set-version against non-release branches
- Clean up build-site needs list

Signed-off-by: Ramon Roche <mrpollo@gmail.com>

.github/workflows/docs-orchestrator.yml

@@ -1,3 +1,13 @@
+# Docs - Orchestrator
+#
+# Trigger paths:
+#   push (main, release/**)  → metadata-regen → build-site → deploy-aws
+#   pull_request              → detect-changes → pr-metadata-regen → link-check → build-site
+#   workflow_dispatch         → metadata-regen → build-site → deploy-aws
+#
+# Container jobs (pr-metadata-regen, metadata-regen) run in px4-dev image and
+# require safe.directory + fetch-depth: 0 for git operations.
+
 name: Docs - Orchestrator
 
 on:
@@ -63,69 +73,11 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
         with:
+          fetch-depth: 0
           submodules: recursive
 
-      - name: Cache Restore - ccache
+      - name: Git ownership workaround
-        id: cache-ccache
+        run: git config --system --add safe.directory '*'
-        uses: actions/cache/restore@v4
-        with:
-          path: ~/.ccache
-          key: ccache-docs-metadata-${{ github.sha }}
-          restore-keys: |
-            ccache-docs-metadata-
-
-      - name: Setup ccache
-        run: |
-          mkdir -p ~/.ccache
-          echo "max_size = 1G" > ~/.ccache/ccache.conf
-
-      - name: Build px4_sitl_default
-        run: |
-          make px4_sitl_default
-        env:
-          CCACHE_DIR: ~/.ccache
-
-      - name: Install Emscripten
-        run: |
-          git clone https://github.com/emscripten-core/emsdk.git /opt/emsdk
-          cd /opt/emsdk
-          ./emsdk install 3.1.64
-          ./emsdk activate 3.1.64
-
-      - name: Build failsafe_web
-        run: |
-          source /opt/emsdk/emsdk_env.sh
-          make failsafe_web
-
-      - name: Sync all metadata
-        run: Tools/ci/metadata_sync.sh --sync all
-
-      - name: Upload metadata artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: pr-metadata
-          path: docs/
-          retention-days: 1
-
-  # =============================================================================
-  # Push Metadata Regen (main/release branches)
-  # =============================================================================
-  metadata-regen:
-    name: "T2: Metadata Sync"
-    if: github.event_name == 'push'
-    permissions:
-      contents: write
-    runs-on: [runs-on,runner=4cpu-linux-x64,image=ubuntu24-full-x64,"run-id=${{ github.run_id }}",spot=false,extras=s3-cache]
-    container:
-      image: px4io/px4-dev:v1.17.0-beta1
-    steps:
-      - uses: runs-on/action@v1
-
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          submodules: recursive
-          token: ${{ secrets.PX4BUILTBOT_PERSONAL_ACCESS_TOKEN }}
 
       - name: Cache Restore - ccache
         id: cache-ccache
@@ -154,20 +106,73 @@ jobs:
           path: ~/.ccache
           key: ccache-docs-metadata-${{ github.sha }}
 
-      - name: Install Emscripten
+      - name: Generate and sync metadata
-        run: |
+        run: Tools/ci/metadata_sync.sh --generate --sync parameters airframes modules msg_docs failsafe_web
-          git clone https://github.com/emscripten-core/emsdk.git /opt/emsdk
+        env:
-          cd /opt/emsdk
+          CCACHE_DIR: ~/.ccache
-          ./emsdk install 3.1.64
-          ./emsdk activate 3.1.64
 
-      - name: Build failsafe_web
+      - name: Upload metadata artifact
-        run: |
+        uses: actions/upload-artifact@v4
-          source /opt/emsdk/emsdk_env.sh
+        with:
-          make failsafe_web
+          name: pr-metadata
+          path: docs/
+          retention-days: 1
 
-      - name: Sync all metadata
+  # =============================================================================
-        run: Tools/ci/metadata_sync.sh --sync all
+  # Push Metadata Regen (main/release branches)
+  # =============================================================================
+  metadata-regen:
+    name: "T2: Metadata Sync"
+    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+    permissions:
+      contents: write
+    runs-on: [runs-on,runner=4cpu-linux-x64,image=ubuntu24-full-x64,"run-id=${{ github.run_id }}",spot=false,extras=s3-cache]
+    container:
+      image: px4io/px4-dev:v1.17.0-beta1
+    steps:
+      - uses: runs-on/action@v1
+
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: recursive
+          token: ${{ secrets.PX4BUILTBOT_PERSONAL_ACCESS_TOKEN }}
+
+      - name: Git ownership workaround
+        run: git config --system --add safe.directory '*'
+
+      - name: Cache Restore - ccache
+        id: cache-ccache
+        uses: actions/cache/restore@v4
+        with:
+          path: ~/.ccache
+          key: ccache-docs-metadata-${{ github.sha }}
+          restore-keys: |
+            ccache-docs-metadata-
+
+      - name: Setup ccache
+        run: |
+          mkdir -p ~/.ccache
+          echo "max_size = 1G" > ~/.ccache/ccache.conf
+
+      - name: Build px4_sitl_default
+        run: |
+          make px4_sitl_default
+        env:
+          CCACHE_DIR: ~/.ccache
+
+      - name: Cache Save - ccache
+        uses: actions/cache/save@v4
+        if: always()
+        with:
+          path: ~/.ccache
+          key: ccache-docs-metadata-${{ github.sha }}
+
+      - name: Generate and sync metadata
+        run: Tools/ci/metadata_sync.sh --generate --sync parameters airframes modules msg_docs failsafe_web
+        env:
+          CCACHE_DIR: ~/.ccache
 
       - name: Setup Node.js
         uses: actions/setup-node@v4
@@ -274,6 +279,7 @@ jobs:
           cat ./logs/link-check-results.md
 
       - name: Post PR comment with link check results
+        if: github.event.pull_request.head.repo.full_name == github.repository
         uses: marocchino/sticky-pull-request-comment@v2
         with:
           header: flaws
@@ -291,7 +297,7 @@ jobs:
   # =============================================================================
   build-site:
     name: "T3: Build Site"
-    needs: [detect-changes, pr-metadata-regen, metadata-regen, link-check]
+    needs: [pr-metadata-regen, metadata-regen, link-check]
     if: >-
       always() &&
       (needs.metadata-regen.result == 'success' || needs.metadata-regen.result == 'skipped') &&
@@ -325,8 +331,11 @@ jobs:
           branch="${{ steps.set-branch.outputs.branchname }}"
           if [[ "$branch" == "main" ]]; then
             version="main"
-          else
+          elif [[ "$branch" =~ ^release/ ]]; then
             version="v${branch#release/}"
+          else
+            echo "::error::Unsupported branch for docs deploy: $branch (expected main or release/*)"
+            exit 1
           fi
           echo "releaseversion=$version" >> $GITHUB_OUTPUT
 
@@ -357,11 +366,11 @@ jobs:
           retention-days: 1
 
   # =============================================================================
-  # Deploy to AWS (push only)
+  # Deploy to AWS (push + workflow_dispatch)
   # =============================================================================
   deploy-aws:
     name: "T4: Deploy"
-    if: github.event_name == 'push'
+    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
     needs: [metadata-regen, build-site]
     permissions:
       id-token: write

Tools/ci/metadata_sync.sh

@@ -233,7 +233,7 @@ sync_modules() {
 }
 
 sync_msg_docs() {
-    local src_dir="build/px4_sitl_default/msg_docs"
+    local src_dir="build/msg_docs"
     local dest_dir="docs/en/msg_docs"
     local middleware_dir="docs/en/middleware"