[ci] Add failure notification for package docs validation

.github/workflows/notify-package-docs-failure.yml

@@ -0,0 +1,42 @@
+name: Notify on Package Docs Validation Failure
+
+on:
+  workflow_run:
+    workflows: ["Validate Package Docs"]
+    types: [completed]
+
+permissions:
+  pull-requests: write
+
+jobs:
+  notify:
+    name: Comment on PR
+    if: github.event.workflow_run.event == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Download failure signal
+        id: artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: docs-validation-failed
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ github.token }}
+          path: .validate-result
+        continue-on-error: true
+
+      - name: Comment on PR
+        if: steps.artifact.outcome == 'success'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RUN_URL: ${{ github.event.workflow_run.html_url }}
+          REPO: ${{ github.repository }}
+        run: |
+          PR_NUMBER=$(cat .validate-result/pr_number)
+          [ -z "$PR_NUMBER" ] && exit 0
+          # Avoid duplicate comments
+          EXISTING=$(gh api "repos/${REPO}/issues/${PR_NUMBER}/comments" \
+            --jq '[.[] | select(.body | contains("Package docs validation failed"))] | length')
+          if [ "$EXISTING" = "0" ]; then
+            printf '⚠️ **Package docs validation failed.** Please check the [workflow run](%s) for details.\n\nFor support, reach out in the #docs Slack channel.\n\ncc @elastic/integration-docs\n' "$RUN_URL" > comment-body.md
+            gh pr comment "$PR_NUMBER" --repo "$REPO" --body-file comment-body.md
+          fi

.github/workflows/validate-package-docs.yml

@@ -38,8 +38,8 @@ jobs:
           fi
 
       - name: Validate with docs-builder
+        id: validate
         if: steps.changed-docs.outputs.skip != 'true'
-        # TODO: set to false once pre-existing doc issues are fixed
         continue-on-error: true
         env:
           CHANGED_FILES: ${{ steps.changed-docs.outputs.files }}
@@ -81,3 +81,19 @@ jobs:
           docker run --rm -v "$PWD/.validate:/workspace" -w /workspace \
             ghcr.io/elastic/docs-builder:edge \
             --metadata-only
+
+      - name: Signal failure for notification workflow
+        if: steps.validate.outcome == 'failure'
+        env:
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          mkdir -p .validate-result
+          echo "$PR_NUMBER" > .validate-result/pr_number
+
+      - name: Upload failure signal
+        if: steps.validate.outcome == 'failure'
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-validation-failed
+          path: .validate-result/
+          retention-days: 1