From e7fb74cadf350fcd739f2f3c602a9945fae07b87 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 28 Oct 2025 11:13:32 +0000
Subject: [PATCH] ci: integrate sync-docs workflow

---
 .github/workflows/__main-ci.yml | 12 +++++++
 SYNC_DOCS_IMPROVEMENTS.md       | 55 +++++++++++++++++++++++++++++++++
 2 files changed, 67 insertions(+)
 create mode 100644 SYNC_DOCS_IMPROVEMENTS.md

diff --git a/.github/workflows/__main-ci.yml b/.github/workflows/__main-ci.yml
index 16131951..8e5f2b76 100644
--- a/.github/workflows/__main-ci.yml
+++ b/.github/workflows/__main-ci.yml
@@ -38,3 +38,15 @@ jobs:
       github-app-id: ${{ vars.CI_BOT_APP_ID }}
     secrets:
       github-app-key: ${{ secrets.CI_BOT_APP_PRIVATE_KEY }}
+
+  sync-docs:
+    needs: ci
+    if: github.event_name != 'schedule'
+    uses: hoverkraft-tech/public-docs/.github/workflows/sync-docs-dispatcher.yml@18facec04f2945f4d66d510e8a06568497b73c54 # 0.1.0
+    with:
+      paths: |
+        actions/**/README.md
+        .github/workflows/*.md
+        README.md
+    secrets:
+      github-token: ${{ secrets.PUBLIC_DOCS_TOKEN }}
diff --git a/SYNC_DOCS_IMPROVEMENTS.md b/SYNC_DOCS_IMPROVEMENTS.md
new file mode 100644
index 00000000..7f3468a8
--- /dev/null
+++ b/SYNC_DOCS_IMPROVEMENTS.md
@@ -0,0 +1,55 @@
+# Sync Documentation Workflow - Implementation Guide
+
+This guide provides instructions for implementing the sync-docs workflow in a repository, based on learnings from integrating it into ci-github-common.
+
+## Quick Implementation
+
+Add the following job to your main CI workflow (e.g., `__main-ci.yml`):
+
+```yaml
+sync-docs:
+  needs: ci # or your primary CI job name
+  if: github.event_name != 'schedule'
+  uses: hoverkraft-tech/public-docs/.github/workflows/sync-docs-dispatcher.yml@18facec04f2945f4d66d510e8a06568497b73c54 # 0.1.0
+  with:
+    paths: |
+      actions/**/README.md
+      .github/workflows/*.md
+      README.md
+  secrets:
+    github-token: ${{ secrets.PUBLIC_DOCS_TOKEN }}
+```
+
+## Key Points for Implementation
+
+1. **Workflow Type**: This is a reusable workflow, not an action. Use `uses:` at the job level.
+
+2. **Version Pinning**: Always pin to a specific commit SHA with version tag comment for security.
+
+3. **Paths Configuration**: Be specific with glob patterns:
+   - Use `actions/**/README.md` instead of `actions/`
+   - Use `.github/workflows/*.md` instead of `.github/workflows/`
+   - Only sync Markdown documentation files
+
+4. **Secret Required**: `PUBLIC_DOCS_TOKEN` must be configured in repository secrets with `repo` scope and `repository_dispatch` write access to public-docs.
+
+5. **Integration Pattern**: Add as a job in main CI workflow after primary CI job completes, skip on scheduled runs.
+
+## YAML Formatting Tips
+
+For long workflow references that may fail yamllint:
+
+- Line was too long, so removed YAML folding (`>-`) and used single line
+- Comment version tag at end of line for clarity
+
+## Upstream Documentation Improvements Needed
+
+The [sync-docs-dispatcher.md](https://github.com/hoverkraft-tech/public-docs/blob/main/.github/workflows/sync-docs-dispatcher.md) should include:
+
+1. **Workflow vs Action**: Clarify this is a reusable workflow (job-level `uses:`), not an action (step-level)
+2. **Complete Example**: Show full workflow file with triggers and permissions, not just the job
+3. **Token Setup**: Detail required scopes, how to obtain/configure `PUBLIC_DOCS_TOKEN`
+4. **Path Patterns**: Recommend using specific glob patterns for Markdown files only
+5. **Version Pinning**: Explain commit SHA pinning strategy and how to update
+6. **YAML Linting**: Show proper line formatting for repositories with strict yamllint rules
+7. **Troubleshooting**: Add verification steps and links to check sync status in both repos