feat: add workflow to auto-sync Management API docs#7577
Merged
kristof-siket merged 3 commits intomainfrom Mar 2, 2026
Merged
Conversation
Adds a GitHub Actions workflow that syncs Management API documentation after each production deployment. Triggered via repository_dispatch from pdp-control-plane or manually via workflow_dispatch. The workflow fetches the live OpenAPI spec, regenerates MDX stubs using fumadocs-openapi, commits any changes, and triggers a Vercel redeploy.
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review infoConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
WalkthroughAdds a new GitHub Actions workflow that generates management API docs from the OpenAPI spec, detects MDX changes under apps/docs/content/docs/management-api/, commits and pushes updates when present, and triggers a Vercel deployment via a webhook. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
|
The latest updates on your projects. Learn more about Argos notifications ↗︎
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
.github/workflows/sync-management-api-docs.yml (1)
63-64: Harden deploy-hook call with timeout and retries.Line 64 has no timeout/retry policy. A transient network issue can fail the workflow even when docs sync succeeded.
Proposed hardening
- - name: Trigger Vercel deploy - run: curl --fail -X POST "${{ secrets.VERCEL_DEPLOY_HOOK_URL }}" + - name: Trigger Vercel deploy + run: | + curl --fail --silent --show-error \ + --max-time 30 \ + --retry 3 \ + --retry-delay 2 \ + --retry-all-errors \ + -X POST "${{ secrets.VERCEL_DEPLOY_HOOK_URL }}"🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.github/workflows/sync-management-api-docs.yml around lines 63 - 64, The "Trigger Vercel deploy" step currently runs a single curl without timeout or retries; update this step to harden the deploy-hook call by adding a per-request timeout and a retry policy—either replace the single curl invocation with a retry loop that attempts curl up to N times with delays between attempts (and uses curl options like --fail and --max-time) or use an existing retry action; ensure the step still fails the job only after all retries are exhausted and include clear logging of attempts and the final error.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.github/workflows/sync-management-api-docs.yml:
- Around line 42-52: Change detection step (id: changes) misses untracked MDX
files because it uses git diff --quiet on apps/docs/content/docs/management-api/
which ignores untracked files; replace the check with a command that detects
untracked and modified files (e.g., use git status --porcelain
apps/docs/content/docs/management-api/ or git ls-files -o --exclude-standard
apps/docs/content/docs/management-api/ and test for non-empty output) and then
set the GITHUB_OUTPUT "changed=true/false" and print the appropriate messages so
newly generated MDX files trigger the commit step.
- Around line 17-20: The workflow currently passes BOT_TOKEN_DOCS_COMMIT to
actions/checkout@v4 which exposes the write-scoped PAT for the entire job
(including the pnpm install step); change the flow so checkout does not use the
token, and instead configure authentication only at push time by (a) removing
token: ${{ secrets.BOT_TOKEN_DOCS_COMMIT }} from the actions/checkout@v4 step
and (b) adding a dedicated step before the git push that sets git credentials or
uses actions/setup-credentials (or similar) to inject BOT_TOKEN_DOCS_COMMIT just
for the push operation (refer to the checkout step and the push step that runs
git push or uses actions/github-script to ensure the token is applied only
there).
---
Nitpick comments:
In @.github/workflows/sync-management-api-docs.yml:
- Around line 63-64: The "Trigger Vercel deploy" step currently runs a single
curl without timeout or retries; update this step to harden the deploy-hook call
by adding a per-request timeout and a retry policy—either replace the single
curl invocation with a retry loop that attempts curl up to N times with delays
between attempts (and uses curl options like --fail and --max-time) or use an
existing retry action; ensure the step still fails the job only after all
retries are exhausted and include clear logging of attempts and the final error.
- Use persist-credentials: false on checkout and inject bot token only at push time to avoid exposing credentials during pnpm install - Use git status --porcelain instead of git diff --quiet to detect both modified and newly created (untracked) MDX files
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a GitHub Actions workflow (
sync-management-api-docs.yml) that automatically keeps Management API documentation in sync after each production deployment.Triggers:
repository_dispatch(management-api-updated) — fired automatically from thepdp-control-planedeploy pipelineworkflow_dispatch— for manual runs (testing/recovery)What it does:
BOT_TOKEN_DOCS_COMMIT(for push access)api.prisma.io/v1/docfumadocs-openapi(generate-docs.ts)Concurrency: Uses a
sync-management-api-docsgroup withcancel-in-progress: falseto prevent parallel runs from conflicting.Required secrets
These must be configured in this repo's Settings > Secrets and variables > Actions before the workflow can run:
BOT_TOKEN_DOCS_COMMITVERCEL_DEPLOY_HOOK_URLRelated
prisma/pdp-control-plane—projects/management-api-docs-sync/spec.mdrepository_dispatchstep inpdp-control-plane's deploy pipeline will be added in a follow-up PR.Test plan
BOT_TOKEN_DOCS_COMMITandVERCEL_DEPLOY_HOOK_URLsecrets to this repoSummary by CodeRabbit