Skip to content

ci: add workflow to check generated docs are in sync on PRs #2069

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
armorbreak001 wants to merge 2 commits into from
+69 −0
Closed

ci: add workflow to check generated docs are in sync on PRs #2069

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0bd46c4
ci: add workflow to check generated docs are in sync on PRs
armorbreak001 Apr 22, 2026
ded1173
ci: harden workflow permissions and checkout security
armorbreak001 Apr 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 69 additions & 0 deletions .github/workflows/check-generated-docs-sync.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
# This workflow verifies that generated documentation files are in sync with source code.
# If a PR modifies JSDoc comments or source files without regenerating docs, this check will fail.
name: 'Check generated docs are up to date'

on:
pull_request:
types: [opened, reopened, synchronize]
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Apr 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 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:

🏁 Script executed:

cat -n .github/workflows/check-generated-docs-sync.yml

Repository: 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.

Suggested change
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.

branches: [master]

permissions:
contents: read

jobs:
check-docs:
name: 'Check generated docs sync'
runs-on: ubuntu-latest
# Skip for bot-generated PRs (docs updates, releases, CI sync)
if: >
!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:
- name: Checkout repository
uses: actions/checkout@v4
with:
persist-credentials: false

- name: Determine what node version to use
uses: asyncapi/.github/.github/actions/get-node-version-from-package-lock@master
with:
node-version: ${{ vars.NODE_VERSION }}
id: lockversion

- name: Use Node.js
uses: actions/setup-node@v4
with:
node-version: "${{ steps.lockversion.outputs.version }}"
cache: 'npm'
cache-dependency-path: '**/package-lock.json'

- name: Install dependencies
run: npm ci

- name: Regenerate documentation assets
run: npm run generate:assets

- name: Check for doc differences
run: |
if git diff --exit-code --quiet -- '*.md'; then
echo "✅ All generated documentation is up to date"
else
echo "::error::Generated documentation is out of sync with source code."
echo "Please run 'npm run generate:assets' locally and commit the updated docs."
echo ""
echo "Changed files:"
git diff --name-only -- '*.md'
exit 1
fi
Loading