Create sync-spec-docs.yml #1
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: Sync API spec docs | ||
| # Regenerate the API documentation in the utcp-specification repo | ||
| # whenever a change lands on main that could affect the REQUIRED | ||
| # docstrings the docs are extracted from. Runs on push (and on | ||
| # workflow_dispatch for manual reruns). | ||
| # | ||
| # Prerequisites: | ||
| # * Repository secret SPEC_SYNC_TOKEN -- a fine-grained or classic | ||
| # PAT (or GitHub App installation token) with `Contents: write` | ||
| # permission on universal-tool-calling-protocol/utcp-specification. | ||
| # A bot account is preferred so the commit attribution is clearly | ||
| # automated. | ||
| on: | ||
| push: | ||
| branches: [main] | ||
| paths: | ||
| - 'core/**' | ||
| - 'plugins/**' | ||
| - 'scripts/extract_required_docs.py' | ||
| - '.github/workflows/sync-spec-docs.yml' | ||
| workflow_dispatch: | ||
| concurrency: | ||
| # Serialize sync runs so two pushes to main don't race each other into | ||
| # the spec repo and produce conflicting commits. | ||
| group: sync-spec-docs | ||
| cancel-in-progress: false | ||
| jobs: | ||
| sync: | ||
| runs-on: ubuntu-latest | ||
| permissions: | ||
| contents: read | ||
| steps: | ||
| - name: Checkout python-utcp | ||
| uses: actions/checkout@v4 | ||
| with: | ||
| path: python-utcp | ||
| - name: Checkout utcp-specification | ||
| uses: actions/checkout@v4 | ||
| with: | ||
| repository: universal-tool-calling-protocol/utcp-specification | ||
| path: utcp-specification | ||
| token: ${{ secrets.SPEC_SYNC_TOKEN }} | ||
| ref: main | ||
| # Fetch full history so the eventual `git push` from this | ||
| # checkout is a fast-forward against origin/main. | ||
| fetch-depth: 0 | ||
| - name: Set up Python | ||
| uses: actions/setup-python@v5 | ||
| with: | ||
| python-version: '3.12' | ||
| - name: Regenerate API docs | ||
| working-directory: python-utcp | ||
| run: | | ||
| # The extractor writes per-module .md files plus an index.md | ||
| # under the chosen output dir. It does NOT prune stale files, | ||
| # so wipe the regenerated subtrees first to avoid leaving | ||
| # orphans behind for modules that were renamed or deleted in | ||
| # this release. LICENSE and NOTICE.md at the api/ root are | ||
| # preserved. | ||
| rm -rf ../utcp-specification/docs/api/core | ||
| rm -rf ../utcp-specification/docs/api/plugins | ||
| python scripts/extract_required_docs.py \ | ||
| --root . \ | ||
| --output ../utcp-specification/docs/api \ | ||
| --dirs core plugins | ||
| - name: Commit and push if changed | ||
| working-directory: utcp-specification | ||
| env: | ||
| SOURCE_SHA: ${{ github.sha }} | ||
| SOURCE_REPO_URL: ${{ github.server_url }}/${{ github.repository }} | ||
| run: | | ||
| git config user.name "utcp-spec-sync[bot]" | ||
| git config user.email "utcp-spec-sync[bot]@users.noreply.github.com" | ||
| git add docs/api | ||
| if git diff --cached --quiet; then | ||
| echo "No spec changes -- nothing to push." | ||
| exit 0 | ||
| fi | ||
| SHORT_SHA="${SOURCE_SHA:0:7}" | ||
| git commit -m "docs(api): sync from python-utcp@${SHORT_SHA} | ||
| Auto-generated by python-utcp .github/workflows/sync-spec-docs.yml. | ||
| Source commit: ${SOURCE_REPO_URL}/commit/${SOURCE_SHA}" | ||
| git push origin main | ||
