ci: add workflow to check generated docs are in sync on PRs#2069
ci: add workflow to check generated docs are in sync on PRs#2069armorbreak001 wants to merge 2 commits intoasyncapi:masterfrom
Conversation
Fixes asyncapi#2038 - Adds a PR workflow that regenerates documentation assets (npm run generate:assets) and fails if generated MD files are out of sync with source code, prompting contributors to run the generate command locally.
armorbreak001
requested review from
asyncapi-bot-eve,
derberg,
jonaslagoni and
magicmatatjahu
as code owners
|
What reviewer looks at during PR reviewThe following are ideal points maintainers look for during review. Reviewing these points yourself beforehand can help streamline the review process and reduce time to merge.
|
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughAdds a GitHub Actions workflow that regenerates documentation assets on PRs to master and verifies Markdown files are unchanged by running a git diff, skipping execution for draft PRs and certain bot actors. Fails the check if generated docs are out of sync. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
.github/workflows/check-generated-docs-sync.yml (1)
15-29: Avoid job-levelifconditionals in workflows that could become required checks.The
check-docsjob uses a job-levelifcondition to skip bot-generated and draft PRs. If this check is added to branch protection rules, skipped PRs won't appear in the GitHub checks list at all, causing the required check to never complete—effectively blocking all matched PRs from merging. Move the skip logic to step-level conditionals instead: the job completes successfully regardless of context, but expensive steps (checkout, install, generate, diff) only run when needed.A cleaner structure sets the skip condition as a job env variable and guards steps with it:
Refactor pattern
check-docs: name: 'Check generated docs sync' runs-on: ubuntu-latest - if: > - !github.event.pull_request.draft && !( + env: + SKIP_CHECK: >- + ${{ github.event.pull_request.draft || ( (github.actor == 'asyncapi-bot' && ( startsWith(github.event.pull_request.title, 'ci: update of files from global .github repo') || startsWith(github.event.pull_request.title, 'chore(release):') || github.event.pull_request.title == 'chore: update generated docs' )) || (github.actor == 'asyncapi-bot-eve' && ( startsWith(github.event.pull_request.title, 'ci: update of files from global .github repo') || startsWith(github.event.pull_request.title, 'chore(release):') )) || (github.actor == 'allcontributors[bot]' && startsWith(github.event.pull_request.title, 'docs: add') ) - ) + ) }} steps: + - if: env.SKIP_CHECK != 'true' + uses: actions/checkout@v4 - - uses: actions/checkout@v4Apply
if: env.SKIP_CHECK != 'true'to the remaining expensive steps.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.github/workflows/check-generated-docs-sync.yml around lines 15 - 29, The job-level conditional on the check-docs job should be removed and replaced by a job that always runs but sets an env flag (e.g., SKIP_CHECK) based on the current condition (the draft/bot title/actor checks shown in the if block); then apply step-level guards (e.g., if: env.SKIP_CHECK != 'true') to the expensive steps such as the checkout step, install/build/generate steps, and the diff/compare step so the job completes successfully even when skipped; update the job named check-docs and the expensive step entries to reference the SKIP_CHECK env var and ensure any final reporting step runs unconditionally so the job never disappears from GitHub checks.
🤖 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/check-generated-docs-sync.yml:
- Line 7: The workflow's pull_request trigger only lists types [opened,
reopened, synchronize], so the job that is skipped for draft PRs (job
conditioned on draft status) won't run when a draft is marked ready; update the
trigger types array to include "ready_for_review" so the workflow runs when a PR
transitions from draft to ready_for_review; locate the pull_request 'types'
array in the workflow and add "ready_for_review" alongside the existing entries
to ensure the docs sync check executes at that transition.
---
Nitpick comments:
In @.github/workflows/check-generated-docs-sync.yml:
- Around line 15-29: The job-level conditional on the check-docs job should be
removed and replaced by a job that always runs but sets an env flag (e.g.,
SKIP_CHECK) based on the current condition (the draft/bot title/actor checks
shown in the if block); then apply step-level guards (e.g., if: env.SKIP_CHECK
!= 'true') to the expensive steps such as the checkout step,
install/build/generate steps, and the diff/compare step so the job completes
successfully even when skipped; update the job named check-docs and the
expensive step entries to reference the SKIP_CHECK env var and ensure any final
reporting step runs unconditionally so the job never disappears from GitHub
checks.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 688d2cdd-2558-41b0-9f8e-a5e3e1d0f661
📒 Files selected for processing (1)
.github/workflows/check-generated-docs-sync.yml
|
|
||
| on: | ||
| pull_request: | ||
| types: [opened, reopened, synchronize] |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
GitHub Actions pull_request ready_for_review activity type
💡 Result:
In GitHub Actions, the pull_request event supports multiple activity types (also called "types"), including ready_for_review. This type triggers a workflow when a draft pull request is marked as ready for review. To use it in a workflow YAML file: on: pull_request: types: [ready_for_review] By default, pull_request workflows trigger on opened, synchronize, and reopened. To include ready_for_review along with defaults for non-draft PRs and updates, combine them: on: pull_request: types: [opened, synchronize, reopened, ready_for_review] jobs: example: if: github.event.pull_request.draft == false runs-on: ubuntu-latest steps: - run: echo "Ready for review!" This is confirmed in official GitHub documentation on events that trigger workflows, which references webhook payloads, and multiple community examples. The ready_for_review corresponds to the pull_request webhook action when a draft PR is marked ready.
Citations:
- 1: https://docs.github.com/actions/using-workflows/events-that-trigger-workflows
- 2: Only run on pull requests that are "ready for review" not "draft" pull request. reviewdog/action-eslint#29
- 3: docs: fix workaround description about
ready_for_reviewpeter-evans/create-pull-request#3939 - 4: https://stackoverflow.com/questions/73948443/github-actions-running-a-workflow-on-non-draft-prs
- 5: https://docs.github.com/en/developers/webhooks-and-events/issue-event-types
- 6: https://docs.github.com/en/webhooks/webhook-events-and-payloads?actionType=ready_for_review
- 7: https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows
🏁 Script executed:
cat -n .github/workflows/check-generated-docs-sync.ymlRepository: asyncapi/generator
Length of output: 2899
Add ready_for_review to trigger the check when draft PRs become ready.
Draft PRs skip this check due to the job-level condition on line 16. When marked ready for review, the ready_for_review event fires, but since it's not in the trigger types (line 7), the workflow won't run until another synchronize or reopened event occurs. Add ready_for_review to ensure the docs sync check runs at the point the PR becomes mergeable.
Proposed fix
- types: [opened, reopened, synchronize]
+ types: [opened, reopened, synchronize, ready_for_review]📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| types: [opened, reopened, synchronize] | |
| types: [opened, reopened, synchronize, ready_for_review] |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.github/workflows/check-generated-docs-sync.yml at line 7, The workflow's
pull_request trigger only lists types [opened, reopened, synchronize], so the
job that is skipped for draft PRs (job conditioned on draft status) won't run
when a draft is marked ready; update the trigger types array to include
"ready_for_review" so the workflow runs when a PR transitions from draft to
ready_for_review; locate the pull_request 'types' array in the workflow and add
"ready_for_review" alongside the existing entries to ensure the docs sync check
executes at that transition.
- Add permissions: contents: read (least privilege) - Add persist-credentials: false to checkout step Addresses SonarCloud security hotspot on workflow file.
|
2 participants
Summary
Fixes #2038
Problem
Contributors can update JSDoc comments and forget to run
npm run generate:assets, causing generated docs (api_components.md,api.md, README TOC, etc.) to silently go out of sync with no CI check to catch them.We already had this problem with #1922 where docs changes were unexpectedly auto-merged.
Solution
Add a PR workflow () that:
master(opened, reopened, synchronize)npm cinpm run generate:assets(runsturbo run generate:assetsacross all packages + README TOC update).mdfiles have diffsnpm run generate:assetslocallyDesign decisions
pr-testing-with-test-project.yml*.mddiffs: Catches not justapi_components.mdbut any generated documentation that may be added in the futureNotes
update-docs-on-docs-commits.ymlworkflow partially redundant for catching stale docs on PRs (that workflow still serves the purpose of auto-creating docs update PRs ondocs:commits to master)Summary by CodeRabbit