Move Astro /api deploy to CI and fix the Astro 7 build guards - #39553
Open
devindford wants to merge 6 commits into
Open
Move Astro /api deploy to CI and fix the Astro 7 build guards#39553devindford wants to merge 6 commits into
devindford wants to merge 6 commits into
Conversation
Adds the preview-branch path prefix funnel, moves fonts/icons under src/assets so they work under that prefix, emits the six Hugo-owned legacy /api redirects, moves pagesJson/llmsTxt output under dist/client/api, adds a build-time containment/coverage guard, resolves @websites-modules from the Hugo module cache, and wires up the local dev proxy, CI preview links, and a deploy script for the eventual cutover.
Deploy execution no longer lives in this repo. `astro/scripts/deploy.mjs`
was the only file here that called the `aws` CLI and hardcoded bucket names
and CloudFront distribution IDs; it is deleted, along with its `deploy:*`
package scripts. The upload now runs as job steps in `documentation-ci`,
matching how Hugo's own deploy is declared here but executed by CI tooling.
`astro/CLAUDE.md` records the rule.
Two build blockers, both verified against the installed astro@7.1.5:
- `staticApiGuard` read `routes` from `astro:build:done`, which Astro 7 does
not pass, so every build died with a TypeError. Routes now come from
`astro:routes:resolved`. The coverage guard could not follow: routes are
route definitions, so the category tree is one dynamic entry and the count
would read 1 against a floor of 150. It counts generated pages instead.
- All 14 `dd_e2e` fixture pages were prerendered into `dist/client`, breaking
the containment guard. They render on demand instead, which the Playwright
suite still exercises.
Also: bare `/{lang}/api` roots in the local dev router, `prefixed()` treating
a slashless path as root-relative, and spec-only changes triggering the
preview-link bot.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
github-actions
Bot
added
Architecture
Contributor
Preview links (active after the
|
janine-c
reviewed
Aug 28, 2026
janine-c
left a comment
janine-c
left a comment
Contributor
There was a problem hiding this comment.
Looks like there's nothing to look at here from a docs team perspective; commenting to get it out of our review queue 🙂
The Astro /api app now publishes to its own bucket behind its own CloudFront distribution rather than overlaying the bucket Hugo deploys into. Three consequences here. build.assets goes back to Astro's default `_astro`. It was `api/_astro` to keep the overlay out of the shared bucket's root; that constraint is gone, and the platform router hardcodes /_astro/, /images/ and /fonts/ as its cacheable S3 fast-path, so anything else silently loses asset caching. deriveSiteUrl gains a DOCS_SITE_URL override, checked ahead of every other branch — the pair to DOCS_PATH_PREFIX in pathPrefix.ts. The platform serves at its distribution root, so canonical URLs come from the distribution domain and there is no branch path segment. No new mode is needed for the prefix itself: pathPrefix already treats an empty-but-set DOCS_PATH_PREFIX as an override. The containment guards accept `_astro/` at root alongside the /api subtrees, in both staticApiGuard and its standalone verifyDist twin. Verified with a full build: 19388 files contained, 158 categories, assets at /_astro/ with no branch prefix, canonical on the distribution domain. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
devindford
changed the title
jhgilbert
approved these changes
Aug 28, 2026
Line wrapping and trailing commas only. Confirmed no behavior change: stripping whitespace and trailing commas leaves all three files byte-identical to HEAD. staticApiGuard tests pass (12/12) and verify:dist still reports 19388 contained files across 158 categories. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Contributor
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What does this PR do? What is the motivation?
Targets
jen.gilbert/astro-base, notmaster.Deploy execution leaves this repo.
astro/scripts/deploy.mjswas the only file here that shelled out to theawsCLI and hardcoded S3 bucket names and CloudFront distribution IDs. It is deleted, along with its fourdeploy:*package scripts. The upload now runs as job steps indocumentation-ci, which matches how Hugo's own deploy already works here: declared inhugo/config/{preview,live}/config.yaml, executed by CI tooling.astro/CLAUDE.mdrecords the rule so this does not drift back.astro/scripts/verifyDist.mjsstays. It verifies the shape ofdist/clientand knows nothing about where that output goes.Two build blockers, both verified against the installed
astro@7.1.5:staticApiGuarddestructuredroutesfromastro:build:done. Astro 7 passes{ pages, dir, assets, logger }, so every build died with aTypeError. Routes now come fromastro:routes:resolved. The coverage guard could not simply follow — routes are route definitions, so the whole category tree is one dynamic[category]entry and a route-based count would report 1 against a floor of 150. It counts generated pages instead.dd_e2efixture pages declaredprerender = trueand were emitted intodist/client/dd_e2e/, failing the containment guard. They now render on demand, which the Playwright suite still exercises.Three smaller fixes: bare
/{lang}/apiroots added to the local dev router,prefixed()treats a slashless path as root-relative, and spec-only changes (hugo/data/api/**) now trigger the preview-link bot.Verification
A full preview build now completes:
staticApiGuard passed: 19388 files contained under /api, 158 categories emitted— a line that could not print before.dist/clientholds onlyapi es fr ja kowith no root files.verify:distpasses standalone. Of 2,242 hrefs on a built category page, none are unprefixed and none are double-prefixed.Tests: 689 headless and 151 Playwright passing,
astro checkreports 0 errors. 14 snapshot tests fail, which I confirmed are pre-existing on a clean tree — they need the gitignored SDK example files that only exist aftermake all-examples.Known issue, deliberately not fixed here: the build warns that
/api/latest/service-scorecardsconflicts with the dynamic category route. Production serves/api/latest/scorecards/as canonical and 301sservice-scorecardsto it, butSLUG_OVERRIDESinviewsBuilder.tsmaps it the other way. That is one category out of 158 and is being tracked separately.Merge readiness
For Datadog employees:
<name>/<description>convention and include the forward slash (/). If you've already created your PR with an incorrect branch name, please rename your branch and open a fresh PR./reviewto run an automated check that catches common issues before a Documentation team member reviews your PR.AI assistance
Claude Code was used to trace the deploy/CI dependencies across
documentation,documentation-ci, andwebsites-images, and to write the changes and their tests.Additional notes
The matching
documentation-cichange must merge first — the astro CI jobs do not exist until it is onmain. Those jobs are gated todevin.ford/astro-routerandjen.gilbert/astro-baseonly, and uploads are additionally behind a feature flag that defaults to off.