Skip to content

[ci] Add blocking PR check for package docs using docs-builder #17879

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

Merged
theletterf merged 6 commits into from
Mar 25, 2026
Merged

[ci] Add blocking PR check for package docs using docs-builder #17879

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
1900bb2
[ci] Add blocking PR check for package docs using docs-builder
theletterf Mar 18, 2026
a758567
Merge branch 'main' into ci/validate-package-docs
theletterf Mar 18, 2026
b17e037
[ci] Exclude knowledge_base and subdirs from package docs check
theletterf Mar 19, 2026
4cfc895
Merge branch 'main' into ci/validate-package-docs
theletterf Mar 19, 2026
d25a664
Merge branch 'main' into ci/validate-package-docs
theletterf Mar 25, 2026
eeb89fd
[ci] Support nested package paths in docs validation trigger
theletterf Mar 25, 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
54 changes: 54 additions & 0 deletions .github/workflows/validate-package-docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
name: Validate Package Docs

on:
pull_request:
types: [opened, synchronize, reopened]
paths:
- 'packages/*/docs/*.md'
- 'packages/*/*/docs/*.md'

permissions:
contents: read

jobs:
validate-package-docs:
name: Validate Package Docs (docs-builder)
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v6
with:
fetch-depth: 0

- name: Find changed package docs
id: changed-docs
run: |
FILES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD \
| grep '^packages/.*/docs/[^/]*\.md$' \
Copy link
Copy Markdown
Collaborator

@mrodm mrodm Mar 25, 2026

Choose a reason for hiding this comment

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

This would be needed to be updated once this issue is done: #17403

Once that issue is completed, there could be packages at different levels. There is an example in this PoC #16966

Copy link
Copy Markdown
Member Author

@theletterf theletterf Mar 25, 2026

Choose a reason for hiding this comment

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

Good heads-up! Both the path trigger (packages/**/docs/*.md) and the grep filter (^packages/.*/docs/[^/]*\.md$) already handle nested package paths like packages/nginx/nginx/docs/README.md, so this should work without changes once #17403 lands.

Copy link
Copy Markdown
Member Author

@theletterf theletterf Mar 25, 2026

Choose a reason for hiding this comment

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

@mrodm Keep me honest here though! :)

Copy link
Copy Markdown
Member Author

@theletterf theletterf Mar 25, 2026

Choose a reason for hiding this comment

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

Actually I was wrong — packages/**/docs/*.md doesn't match nested paths. Fixed in the latest commit: now uses two explicit patterns (packages/*/docs/*.md and packages/*/*/docs/*.md) so both current and nested package structures (per #17403) are covered. The grep filter was already fine since .* in regex has no depth limit.

Copy link
Copy Markdown
Collaborator

@mrodm mrodm Mar 25, 2026

Choose a reason for hiding this comment

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

Thanks!
Checking again this regex and I think it works as it should, once it is added the other level of directories:

 $ echo packages/nginx/nginx_otel/docs/README.md |  grep '^packages/.*/docs/[^/]*\.md$'
packages/nginx/nginx_otel/docs/README.md

| grep -v '_dev/build/' || true)
echo "files<<EOF" >> $GITHUB_OUTPUT
echo "$FILES" >> $GITHUB_OUTPUT
echo "EOF" >> $GITHUB_OUTPUT
if [ -z "$FILES" ]; then
echo "skip=true" >> $GITHUB_OUTPUT
else
echo "skip=false" >> $GITHUB_OUTPUT
fi

- name: Generate validation docset
if: steps.changed-docs.outputs.skip != 'true'
env:
CHANGED_FILES: ${{ steps.changed-docs.outputs.files }}
run: |
echo "project: 'Package Docs Validation'" > docset.yml
echo "toc:" >> docset.yml
echo "$CHANGED_FILES" | while read f; do
[ -n "$f" ] && echo " - file: $f" >> docset.yml
done

- name: Run docs-builder validation
if: steps.changed-docs.outputs.skip != 'true'
uses: elastic/docs-builder@main
with:
metadata-only: 'true'
strict: 'true'
Loading