Add tutorial branch automation workflow and script #3
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: Docs Sync → cosmos/docs | ||
| # Runs when docs/ files change on main. | ||
| # Transforms .md → .mdx and opens a PR on the docs site repo. | ||
| # If a sync PR is already open, updates it instead of opening a new one. | ||
| # Skip if the commit was itself produced by the sync (loop guard). | ||
| on: | ||
| push: | ||
| branches: | ||
| - main | ||
| paths: | ||
| - "docs/**" | ||
| jobs: | ||
| sync: | ||
| name: Sync docs to cosmos/docs | ||
| runs-on: ubuntu-latest | ||
| # Loop guard: skip commits that the docs-sync bot created | ||
| if: "!contains(github.event.head_commit.message, '[docs-sync]')" | ||
| steps: | ||
| - name: Checkout example repo | ||
| uses: actions/checkout@v4 | ||
| - name: Set up Python | ||
| uses: actions/setup-python@v5 | ||
| with: | ||
| python-version: "3.12" | ||
| - name: Checkout cosmos/docs | ||
| uses: actions/checkout@v4 | ||
| with: | ||
| repository: cosmos/docs | ||
| # Fine-grained PAT with contents:write and pull-requests:write on cosmos/docs | ||
| token: ${{ secrets.DOCS_REPO_TOKEN }} | ||
| path: cosmos-docs | ||
| - name: Transform docs → Mintlify format | ||
| run: | | ||
| python3 scripts/docs-sync/transform.py \ | ||
| --direction to-mintlify \ | ||
| --input docs/ \ | ||
| --output-dir cosmos-docs/sdk/next/tutorials/example/ | ||
| - name: Check for changes | ||
| id: diff | ||
| run: | | ||
| cd cosmos-docs | ||
| git diff --quiet && echo "changed=false" >> "$GITHUB_OUTPUT" || echo "changed=true" >> "$GITHUB_OUTPUT" | ||
| - name: Open or update PR on cosmos/docs | ||
| if: steps.diff.outputs.changed == 'true' | ||
| env: | ||
| GH_TOKEN: ${{ secrets.DOCS_REPO_TOKEN }} | ||
| run: | | ||
| cd cosmos-docs | ||
| git config user.name "docs-sync[bot]" | ||
| git config user.email "docs-sync[bot]@users.noreply.github.com" | ||
| # Check for an existing open sync PR | ||
| EXISTING=$(gh pr list \ | ||
| --repo cosmos/docs \ | ||
| --label "docs-sync" \ | ||
| --state open \ | ||
| --json number,headRefName \ | ||
| --jq '.[0]') | ||
| if [ -n "$EXISTING" ]; then | ||
| PR_NUMBER=$(echo "$EXISTING" | jq -r '.number') | ||
| BRANCH=$(echo "$EXISTING" | jq -r '.headRefName') | ||
| # Update the existing branch | ||
| git fetch origin "$BRANCH" | ||
| git checkout "$BRANCH" | ||
| git add sdk/next/tutorials/example/ | ||
| git commit -m "docs: sync example tutorials from cosmos/example [docs-sync] | ||
| Auto-synced from cosmos/example@${{ github.sha }} | ||
| Source commit: ${{ github.event.head_commit.message }}" | ||
| git push origin "$BRANCH" | ||
| gh pr comment "$PR_NUMBER" \ | ||
| --repo cosmos/docs \ | ||
| --body "$(cat <<'EOF' | ||
| ## Sync updated | ||
| A new commit was pushed to **cosmos/example** before this PR was merged. This PR's branch has been updated with the latest changes. | ||
| **New commit:** ${{ github.sha }} | ||
| **Triggered by:** ${{ github.event.head_commit.message }} | ||
| Please re-review the diff before merging. | ||
| 🤖 docs-sync bot | ||
| EOF | ||
| )" | ||
| echo "Updated existing PR #$PR_NUMBER" | ||
| else | ||
| # No existing PR — create a new branch and open one | ||
| BRANCH="docs-sync/example-$(date +%Y%m%d-%H%M%S)" | ||
| git checkout -b "$BRANCH" | ||
| git add sdk/next/tutorials/example/ | ||
| git commit -m "docs: sync example tutorials from cosmos/example [docs-sync] | ||
| Auto-synced from cosmos/example@${{ github.sha }} | ||
| Source commit: ${{ github.event.head_commit.message }}" | ||
| git push origin "$BRANCH" | ||
| gh pr create \ | ||
| --repo cosmos/docs \ | ||
| --head "$BRANCH" \ | ||
| --base main \ | ||
| --title "docs: sync example tutorials from cosmos/example" \ | ||
| --label "docs-sync" \ | ||
| --body "$(cat <<'EOF' | ||
| ## Automated docs sync | ||
| This PR was auto-generated by the [docs-sync workflow](https://github.com/cosmos/example/blob/main/.github/workflows/docs-sync.yml) in **cosmos/example**. | ||
| **Source commit:** ${{ github.sha }} | ||
| **Triggered by:** ${{ github.event.head_commit.message }} | ||
| ### What changed | ||
| Transformed \`docs/*.md\` → \`sdk/next/tutorials/example/*.mdx\`: | ||
| - Stripped \`# H1\` headings → YAML frontmatter | ||
| - Rewrote \`https://docs.cosmos.network/...\` links → relative paths | ||
| - Renamed \`.md\` extensions → \`.mdx\` | ||
| ### Review checklist | ||
| - [ ] Mintlify frontmatter looks correct | ||
| - [ ] Links render correctly in preview | ||
| - [ ] Navigation in \`docs.json\` is up to date | ||
| > **Do not edit these files directly** — edit the source in cosmos/example and let the sync bot update them. Changes made here will be synced back automatically. | ||
| 🤖 Generated by docs-sync bot | ||
| EOF | ||
| )" | ||
| fi | ||
