Migrate docs site from Netlify to Cloudflare Workers by matthewp · Pull Request #14025 · withastro/docs

matthewp · 2026-06-09T14:27:17Z

Migrates the Astro docs site from Netlify to Cloudflare Workers.

Changes

Replace Netlify build script with wrangler deploy
Update preview site URL to use Workers CI branch previews
Add wrangler.jsonc configuration for static asset serving
Add .assetsignore to exclude _worker.js and _routes.json from assets
Update .gitignore to ignore .wrangler instead of .netlify
Add wrangler as a dev dependency
Allow workerd build script in pnpm-workspace.yaml
Add GitHub Actions deploy workflow with preview URLs

- Replace Netlify build script with wrangler deploy - Update preview site URL to use Workers CI branch previews - Add wrangler.jsonc configuration for static asset serving - Add .assetsignore to exclude _worker.js and _routes.json - Update .gitignore to ignore .wrangler instead of .netlify - Add wrangler as a dev dependency

- Production: wrangler deploy on push to main - PRs: wrangler versions upload with branch-name alias - Comments preview URL on PRs - Enable preview_urls in wrangler config

github-actions · 2026-06-09T14:48:22Z

Preview deployment

✅ Deployment complete!

https://migrate-cloudflare-2.previews.docs.astro.build

netlify · 2026-06-09T15:08:19Z

❌ Deploy Preview for astro-docs-2 failed. Why did it fail? →

Name	Link
🔨 Latest commit	`116d5df`
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/6a2822c990a4f20008240d90

netlify · 2026-06-09T15:08:29Z

❌ Deploy Preview for astro-docs-2 failed. Why did it fail? →

Name	Link
🔨 Latest commit	`929a755`
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/6a2822fdcb672f0008c83177

netlify · 2026-06-09T15:08:42Z

❌ Deploy Preview for astro-docs-2 failed. Why did it fail? →

Name	Link
🔨 Latest commit	`d2566f6`
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/6a2823506a1d07000816fcf9

netlify · 2026-06-09T15:13:27Z

❌ Deploy Preview for astro-docs-2 failed. Why did it fail? →

Name	Link
🔨 Latest commit	`b78e7f2`
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/6a2c448bf2dc2500088144f3

astro-og-canvas caches rendered images in node_modules/.astro-og-canvas. Without caching this directory, every build regenerates thousands of OG images (~300ms each), adding ~10 minutes to the build.

…4 Worker - Remove .assetsignore (only needed for SSR sites) - Remove deploy script from package.json (CI calls wrangler directly) - Remove observability from wrangler.jsonc (static site) - Add worker.js for serving localized 404 pages - Remove commented-out 404 redirect from _redirects

matthewp · 2026-06-09T18:41:10Z

This uses a worker to do the localized 404 pages. Examples:

delucis

Some early feedback!

delucis · 2026-06-11T15:41:21Z

+      - name: Comment deployment complete
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
+        with:
+          script: |
+            const previewUrl = '${{ steps.preview-url.outputs.url }}';
+            const body = `**Preview deployment**\n\n✅ Deployment complete!\n\n${previewUrl}`;
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+            const existing = comments.find(c => c.body.includes('**Preview deployment**'));
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              });
+            }


This won’t work for PRs from forks will it? They aren’t allowed the issues.write permission (otherwise a fork could open a PR and delete all our issues/PRs for example).

No, forks get downgraded permissions and don't have access to secrets. We're not using pull_request_target. Still, I added a gate so that these parts don't run on forks. The build will still run be there isn't a preview release.

Right, but we need deploy previews and comments for forks, many of our contributors use forks and we rely on being able to easily check their changes.

Ok, I think I have a good solution for this:

In the pull request it doesn't do a deployment, it just builds and uploads the artifact.

A separate workflow runs in the context of main and is triggered by the Deploy workflow finishing. This has access to secrets since it runs from the main repo, not the fork, it downloads the artifacts, deploys the preview, and adds the comment.

- Replace manual wrangler commands with cloudflare/wrangler-action@v3 - Add JSDoc comment to worker.js explaining localized 404 behavior - Addresses review feedback from delucis

Split preview deployment into a separate workflow_run-triggered workflow so fork PRs get deploy previews without exposing secrets. - deploy.yml: builds for all PRs, uploads build output + PR metadata as artifacts, only uses secrets for production deploys on main - deploy-preview.yml: triggered by workflow_run, downloads artifacts, deploys preview to Cloudflare, and comments on the PR with write permissions from the base repo context Fork code never executes with access to secrets. The workflow_run job only deploys pre-built static artifacts. Also pins cloudflare/wrangler-action to exact commit SHA.

delucis

This seems like a smart way to do it!

Do you think we could test the workflow somehow before merging? Or are we at the mercy of merging to main to figure out if it works? The code looks fine to me though.

Left some feedback, but getting the comment template tuned just as we want it doesn’t have to be blocking, I don’t think.

I’d encourage @withastro/maintainers-docs to take a look too as they might be even more directly impacted than me.

- Add comment explaining ALIAS subdomain sanitization - Add concurrency control to prevent race conditions between preview runs - Check comment author (github-actions[bot]) before updating PR comments - Include commit SHA, preview URL, and workflow run link in all PR comments

ArmandPhilippot

Well, I come after the battle... this seems good to me! Great job to both of you! 🙌🏽

I left a question on the deploy workflow. IIUC, I think we need to add v7 there (and remove that once released).

Trigger the deploy workflow on pushes to version branches and allow deploys from those refs. Each version branch will need its own wrangler.jsonc with a unique Worker name (cherry-picked after merge).

matthewp added 10 commits June 9, 2026 08:49

Fix CI: approve workerd build script for pnpm

6458343

Merge main into migrate-cloudflare

ea63f3a

Allow workerd build script in pnpm-workspace.yaml

f305b5c

Trigger CI

06e03b3

Increase Node.js heap size for Workers Builds

37ec087

Remove build command from wrangler config

9b54083

Add GitHub Actions deploy workflow with preview URLs

2625f78

- Production: wrangler deploy on push to main - PRs: wrangler versions upload with branch-name alias - Comments preview URL on PRs - Enable preview_urls in wrangler config

Trigger CI

1705840

Fix preview URL domain

116d5df

github-actions Bot added the 🚨 action label Jun 9, 2026

matthewp added 4 commits June 9, 2026 10:28

Trigger CI

929a755

Trigger CI

d2566f6

Use GITHUB_HEAD_REF for preview site URL

1e22831

Cache Astro build artifacts between CI runs

5bfb1e5

Add deployment status to PR comment

15d051b

matthewp added 7 commits June 9, 2026 11:20

Comment out 404 redirect unsupported by Cloudflare

a7db42e

Fix worker name to 'docs'

ec11967

Cache OG images between builds

b083fba

astro-og-canvas caches rendered images in node_modules/.astro-og-canvas. Without caching this directory, every build regenerates thousands of OG images (~300ms each), adding ~10 minutes to the build.

Trigger CI to test OG cache

02b725c

Fix ESLint: declare Worker globals

7bf0eeb

Add ASSETS binding for Worker to fetch static assets

17ccfb0

matthewp marked this pull request as ready for review June 9, 2026 18:41

delucis reviewed Jun 11, 2026

View reviewed changes

matthewp added 4 commits June 11, 2026 16:12

Use cloudflare/wrangler-action and add Worker docs

fef98c4

- Replace manual wrangler commands with cloudflare/wrangler-action@v3 - Add JSDoc comment to worker.js explaining localized 404 behavior - Addresses review feedback from delucis

Disallow workerd build script

ff7a091

Skip deploy and PR comments for fork PRs

30b4701

delucis reviewed Jun 12, 2026

View reviewed changes

Comment thread .github/workflows/deploy.yml

Comment thread .github/workflows/deploy-preview.yml

Comment thread .github/workflows/deploy-preview.yml Outdated

Comment thread .github/workflows/deploy-preview.yml Outdated

Comment thread .github/workflows/deploy-preview.yml Outdated

ArmandPhilippot reviewed Jun 12, 2026

View reviewed changes

Comment thread .github/workflows/deploy.yml Outdated

matthewp added 2 commits June 12, 2026 13:37

Support deploying version branches (v4, v5, v6)

1162f5a

Trigger the deploy workflow on pushes to version branches and allow deploys from those refs. Each version branch will need its own wrangler.jsonc with a unique Worker name (cherry-picked after merge).

Add v7 to version branch deploy list

b78e7f2

matthewp merged commit 61f4b8f into main Jun 12, 2026
9 of 13 checks passed

matthewp deleted the migrate-cloudflare-2 branch June 12, 2026 18:04

morinokami mentioned this pull request Jun 14, 2026

i18n(ja): update markdown-content.mdx #14057

Merged

Uh oh!

Conversation

matthewp commented Jun 9, 2026

Changes

Uh oh!

github-actions Bot commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify Bot commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

❌ Deploy Preview for astro-docs-2 failed. Why did it fail? →

Uh oh!

netlify Bot commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

❌ Deploy Preview for astro-docs-2 failed. Why did it fail? →

Uh oh!

netlify Bot commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

❌ Deploy Preview for astro-docs-2 failed. Why did it fail? →

Uh oh!

netlify Bot commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

❌ Deploy Preview for astro-docs-2 failed. Why did it fail? →

Uh oh!

matthewp commented Jun 9, 2026

Uh oh!

delucis left a comment

Choose a reason for hiding this comment

Uh oh!

delucis Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

matthewp Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

delucis Jun 12, 2026

Choose a reason for hiding this comment

Uh oh!

matthewp Jun 12, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

delucis left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ArmandPhilippot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions Bot commented Jun 9, 2026 •

edited

Loading

netlify Bot commented Jun 9, 2026 •

edited

Loading

netlify Bot commented Jun 9, 2026 •

edited

Loading

netlify Bot commented Jun 9, 2026 •

edited

Loading

netlify Bot commented Jun 9, 2026 •

edited

Loading