.github/workflows/hugo.yaml runs only on push to main, so no pull request is ever built. A change that breaks the site build is discovered after it lands, on the branch that publishes.
Mechanism
The workflow's trigger has no pull_request entry, so the only build of a proposed change happens once it is already merged. Nothing else in .github/workflows/ builds the site: i18n-lint.yml runs the translation digest check, fetch-telemetry.yml and update-oss-health.yaml are scheduled data refreshes.
Hugo treats an unresolvable {{% ref %}} as an error rather than rendering a dead link — refLinksErrorLevel is unset, so it defaults to ERROR — which means a single mistyped internal link fails the build outright. Front matter errors and shortcode misuse fail the same way.
Worth knowing before fixing it
The production configuration excludes docs/next/** from every language mount, and hugo --gc --minify defaults to production. So the obvious command does not validate anything under next/, which is where in-flight documentation for the upcoming release lives. Measured by injecting a deliberately unresolvable ref into a page under next/: hugo --gc --minify exits 0 with no errors, while hugo --environment development --gc --minify exits 1 and names the file and column.
A pull-request check that runs only the production build would therefore pass on a broken next/ page and give false assurance — worse than no check, because it makes the gap look covered.
Fix shape
Add a pull_request trigger that builds both environments, or at minimum the development one, since that is the configuration under which next/ is rendered at all. ./hack/download_openapi.sh runs first and npm install is required — Docsy resolves its SCSS through PostCSS, and without the install the build fails pointing at an unrelated page, which is a confusing first failure for anyone adding this.
.github/workflows/hugo.yamlruns only on push tomain, so no pull request is ever built. A change that breaks the site build is discovered after it lands, on the branch that publishes.Mechanism
The workflow's trigger has no
pull_requestentry, so the only build of a proposed change happens once it is already merged. Nothing else in.github/workflows/builds the site:i18n-lint.ymlruns the translation digest check,fetch-telemetry.ymlandupdate-oss-health.yamlare scheduled data refreshes.Hugo treats an unresolvable
{{% ref %}}as an error rather than rendering a dead link —refLinksErrorLevelis unset, so it defaults toERROR— which means a single mistyped internal link fails the build outright. Front matter errors and shortcode misuse fail the same way.Worth knowing before fixing it
The production configuration excludes
docs/next/**from every language mount, andhugo --gc --minifydefaults to production. So the obvious command does not validate anything undernext/, which is where in-flight documentation for the upcoming release lives. Measured by injecting a deliberately unresolvablerefinto a page undernext/:hugo --gc --minifyexits 0 with no errors, whilehugo --environment development --gc --minifyexits 1 and names the file and column.A pull-request check that runs only the production build would therefore pass on a broken
next/page and give false assurance — worse than no check, because it makes the gap look covered.Fix shape
Add a
pull_requesttrigger that builds both environments, or at minimum the development one, since that is the configuration under whichnext/is rendered at all../hack/download_openapi.shruns first andnpm installis required — Docsy resolves its SCSS through PostCSS, and without the install the build fails pointing at an unrelated page, which is a confusing first failure for anyone adding this.