[ci] Add blocking PR check for package docs using docs-builder#17879
[ci] Add blocking PR check for package docs using docs-builder#17879theletterf merged 6 commits intomainfrom
Conversation
Adds a new workflow that validates changed packages/**/docs/*.md files
on every PR using the elastic/docs-builder action (metadata-only + strict
mode), catching Elastic-specific syntax issues before they reach EPR/downstream.
_dev/build/ template files are excluded since they contain {{ fields }}
syntax that is not valid docs-builder input.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
+CC @elastic/docs-engineering @elastic/integration-docs |
Narrows the path trigger from packages/**/docs/** to packages/**/docs/*.md and tightens the grep filter to [^/]*.md$ so only top-level docs files are validated, excluding knowledge_base/ and other subdirectories. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
Good catch — fixed in the latest commit. Both the path trigger and the grep filter now exclude subdirectories under |
|
@elastic/ecosystem Please have a look, thanks! |
|
@elastic/ecosystem Could you have a look / approve? |
mrodm
left a comment
mrodm
left a comment
There was a problem hiding this comment.
LGTM.
Just wondering if the filtering could be updated to be able to detect those other level of packages.
It could be done also in a follow-up.
| id: changed-docs | ||
| run: | | ||
| FILES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD \ | ||
| | grep '^packages/.*/docs/[^/]*\.md$' \ |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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
Replace packages/**/docs/*.md with explicit single- and two-level patterns so the workflow also triggers for nested packages like packages/nginx/nginx/docs/README.md (see #17403). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
5 participants
Summary
.github/workflows/validate-package-docs.yml— a new blocking PR check that runselastic/docs-builder(metadata-only + strict mode) against anypackages/**/docs/*.mdfiles changed in a PRdocset.ymlat the repo root listing only the changed files, so no static manifest needs to be maintained_dev/build/paths (those contain{{ fields }}template syntax not valid for docs-builder)Why
Vale linting already runs but is non-blocking (
fail_on_error: false). Badly formatted Markdown or invalid docs-builder directives can slip intopackages/*/docs/README.mdfiles and break downstream consumers (EPR /integration-docsrepo) silently. This check catches those issues at PR time.Test plan
packages/*/docs/README.mdwith intentionally broken Markdown — confirmValidate Package Docs (docs-builder)check appears and fails🤖 Generated with Claude Code