ci/docs: deploy documentation site on Cloudflare with PR previews by ifireball · Pull Request #225 · fullsend-ai/fullsend

ifireball · 2026-04-12T07:53:57Z

Summary

Moves documentation site hosting to Cloudflare Workers with GitHub Deployments so each open pull request can publish its own preview URL. Reviewers can validate rendered docs, links, and layout in a browser instead of relying only on Markdown and workflow diffs.

What changed

Replace .github/workflows/mindmap.yml with site-build.yml and site-deploy.yml.
Add site/wrangler.toml and site/public/ for static assets.
Add docs/site-deployment.md (operator runbook) and design/spec material under docs/superpowers/.

Ran make lint locally before pushing, as recommended in CONTRIBUTING.md.

Host the static documentation site on Cloudflare Workers and wire GitHub Deployments so each pull request can publish an isolated preview URL. Reviewers can open the rendered site for a change instead of inferring layout and navigation from diffs alone. This removes the GitHub Pages mindmap workflow in favor of site build and deploy workflows, adds site/wrangler.toml, operator guidance in docs/site-deployment.md, and design/spec notes under docs/superpowers/.

waynesun09

Overall the two-workflow pattern is well-designed — fork safety, secret isolation, and artifact flow are solid. A few items to address before merging:

Must fix:

--assets public CLI flag on versions upload may override wrangler.toml asset config (including not_found_handling), creating divergence between preview and production
Verify deployment-url output from wrangler-action for versions upload --preview-alias returns the alias URL, not the internal versioned URL

Should fix:

URL parsing fallback matches workers.dev as substring — tighten to \.workers\.dev
Preview alias uses workflow_run.id instead of PR number — creates stale alias sprawl
per_page: 100 on comment listing may miss marker comment on busy PRs
Fork PR number resolution silently skips on ambiguous match — use core.warning
Plan doc references site-github-pages.yml but the deleted file is mindmap.yml

waynesun09 · 2026-04-13T16:32:54Z

+          fi
+          if [ -z "$url" ]; then
+            comb="${OUT_PROD:-}${ERR_PROD:-}${OUT_PR:-}${ERR_PR:-}"
+            url=$(printf '%s' "$comb" | grep -oE 'https://[a-zA-Z0-9._/?#&=%_-]+' | grep 'workers.dev' | head -1 || true)


Security — URL parsing matches workers.dev as substring

grep 'workers.dev' would also match deceptive domains like evil-workers.dev.attacker.com. This URL ends up as environment_url in a GitHub Deployment and rendered as a clickable link in the PR comment.

Suggest tightening to:

grep -E '\.workers\.dev(/|$)'

waynesun09 · 2026-04-13T16:32:56Z

+          command: >-
+            versions upload
+            --name="${{ vars.CLOUDFLARE_PROJECT_NAME }}"
+            --assets public
+            --preview-alias pr-${{ github.event.workflow_run.id }}


Inconsistent asset config between preview and production paths

The preview command passes --assets public explicitly here, but the production deploy (line 48) does NOT pass --assets and relies on wrangler.toml's [assets] directory = "./public". Two concerns:

The CLI --assets flag may override the entire asset config block from wrangler.toml, meaning not_found_handling = "single-page-application" might not apply to previews.

Behavior divergence between preview and production — what reviewers see in preview may not match what ships to production.

Consider removing --assets public and letting wrangler.toml govern both paths consistently, or verify that the CLI flag preserves the [assets] table settings.

waynesun09 · 2026-04-13T16:32:57Z

+            versions upload
+            --name="${{ vars.CLOUDFLARE_PROJECT_NAME }}"
+            --assets public
+            --preview-alias pr-${{ github.event.workflow_run.id }}


Preview alias uses workflow_run.id instead of PR number

pr-${{ github.event.workflow_run.id }} produces aliases like pr-12345678901 which are not human-readable and create a new alias on every re-run (stale alias sprawl). Using the resolved PR number instead (e.g., pr-225) would produce stable, predictable preview URLs.

This would require resolving the PR number before the wrangler step — a structural change, but worth considering since the PR number resolution logic already exists later in the workflow.

waynesun09 · 2026-04-13T16:32:59Z

+        if: >-
+          (steps.cf-prod.outcome == 'success' || steps.cf-preview.outcome == 'success')
+        env:
+          URL_PROD: ${{ steps.cf-prod.outputs.deployment-url }}


Verify deployment-url output for versions upload

wrangler-action extracts deployment-url from wrangler's structured output. For wrangler deploy this reliably returns the production URL, but for versions upload --preview-alias it's unclear whether the output contains the alias URL (e.g., pr-XXX.<worker>.workers.dev) or the internal versioned URL. If it returns the versioned URL, the preview comment will show a less stable link. The grep fallback at line 84 helps but depends on wrangler output format. Worth validating with a test run.

waynesun09 · 2026-04-13T16:33:00Z

+              owner,
+              repo,
+              issue_number: prNumber,
+              per_page: 100,


per_page: 100 may miss existing marker comment

On heavily-discussed PRs with 100+ comments (e.g., bot activity from multiple tools), the marker comment could be on a later page, causing a duplicate comment to be created. Consider paginating or documenting this as a known limitation.

waynesun09 · 2026-04-13T16:33:01Z

+            let prNumber = run.pull_requests?.[0]?.number;
+            if (!prNumber) {
+              const head = `${run.head_repository.owner.login}:${run.head_branch}`;
+              const { data: prs } = await github.rest.pulls.list({
+                owner,
+                repo,
+                state: 'open',
+                head,
+                per_page: 100,
+              });
+              if (prs.length !== 1) {
+                core.info(`Skipping PR comment: expected 1 open PR for head=${head}, found ${prs.length}`);
+                return;
+              }
+              prNumber = prs[0].number;


PR number resolution unreliable for fork PRs

workflow_run.pull_requests is documented as empty when head and base repos differ (fork PRs). The pulls.list fallback with head=owner:branch is generally correct, but silently skips the comment if the fork owner has multiple open PRs from the same branch name. Consider logging a warning (core.warning) instead of core.info so this is more visible in the Actions log.

waynesun09 · 2026-04-13T16:33:03Z

+| `.github/workflows/site-deploy.yml` | Checkout + artifact → `site/public/`, `wrangler deploy` / `versions upload`, GitHub Deployment + PR comment |
+| `site/wrangler.toml` | Worker name placeholder, `assets.directory = public`, SPA `not_found_handling`, `preview_urls` |
+| `site/public/.gitkeep` | Keeps `public/` in git; CI overwrites with artifact contents |
+| `.github/workflows/site-github-pages.yml` | **Removed** (replaced by `site-build.yml` / `site-deploy.yml`) |


Wrong filename — references site-github-pages.yml but the actual deleted file is mindmap.yml. This appears in the file map and again in Task 3 (lines 118, 122, 127).

- Resolve PR number early for stable --preview-alias pr-<n>; fall back to workflow_run.id with a warning when multiple open PRs share the same head. - Drop --assets public from versions upload so wrangler.toml governs SPA not_found_handling for preview and production. - Tighten workers.dev URL extraction to avoid deceptive hostnames. - Paginate PR comment search; gate deployment script on meta success; warn when preview URL omits the alias token (versioned URL hint). - Fix plan/spec/runbook: removed workflow was mindmap.yml; document alias behavior. Made-with: Cursor

ifireball · 2026-04-14T07:59:33Z

Pushed 7a395b7 addressing @waynesun09’s review:

Must fix

Dropped --assets public from versions upload so site/wrangler.toml [assets] (including not_found_handling) applies to previews the same as production.
Added a Validate preview Workers URL step: if deployment-url does not contain the preview-alias token (e.g. pr-225), the job emits an ::warning:: so logs flag a possible versioned URL vs alias hostname (without failing the deploy).

Should fix

URL fallback grep now requires \.workers\.dev(/|$) so deceptive hostnames are not picked up.
Preview alias uses resolved PR number when unique; only falls back to workflow_run.id when pulls.list finds multiple open PRs for the same head (with core.warning).
PR comment listing paginates (up to 20×100 comments) to find the marker.
Ambiguous / missing PR for the comment path uses core.warning (no silent info).
Plan/spec/runbook: removed workflow is mindmap.yml, not site-github-pages.yml; docs describe alias + fallback.

CI lint / build (Build Site) are green on this push. Please take another look when you have a moment.

waynesun09

All 7 items from my previous review are resolved in 7a395b7. Verified each fix against the current diff:

--assets public dropped — wrangler.toml governs both paths consistently
Preview URL validation step added (warns if alias token missing, doesn't block)
URL grep anchored to \.workers\.dev(/|$)
PR number resolved before wrangler step — stable pr-<number> aliases, fallback to workflow_run.id only on ambiguous head with core.warning
Comment listing paginates (20×100)
Ambiguous/missing PR uses core.warning throughout
Plan/spec/runbook corrected to reference mindmap.yml

Clean restructuring, no new issues.

ifireball force-pushed the ifireball/site-cloudflare-workers branch from e413c1b to ef21046 Compare April 12, 2026 07:58

ifireball changed the title ~~ci/docs: publish documentation site on Cloudflare Workers~~ ci/docs: deploy documentation site on Cloudflare with PR previews Apr 12, 2026

ifireball force-pushed the ifireball/site-cloudflare-workers branch from ef21046 to 5b24708 Compare April 12, 2026 07:59

ifireball self-assigned this Apr 12, 2026

ifireball marked this pull request as ready for review April 12, 2026 08:03

ifireball requested review from ggallen, maruiz93 and ralphbean April 12, 2026 08:04

rh-hemartin approved these changes Apr 13, 2026

View reviewed changes

waynesun09 requested changes Apr 13, 2026

View reviewed changes

maruiz93 approved these changes Apr 13, 2026

View reviewed changes

ifireball requested a review from waynesun09 April 14, 2026 08:02

waynesun09 approved these changes Apr 14, 2026

View reviewed changes

ifireball added this pull request to the merge queue Apr 15, 2026

Merged via the queue into fullsend-ai:main with commit 76bd160 Apr 15, 2026
2 checks passed

ifireball deleted the ifireball/site-cloudflare-workers branch April 15, 2026 07:43

This was referenced Jun 23, 2026

docs(adr): ADR 0067 — GitLab cron-polling event dispatch #2583

Merged

fix(ci): skip e2e/functional tests in merge queue for irrelevant paths #2617

Merged

This was referenced Jul 2, 2026

feat: add vouch system for first-time contributors #2934

Merged

docs: remove stale retro.env references from retro agent plan #2946

Closed

This was referenced Jul 16, 2026

feat(#5027): add custom robots.txt and llms.txt for AI bot access #5130

Merged

fix(version)!: resolve CLI version from reusable workflow ref #5357

Merged

qodo-code-review Bot mentioned this pull request Aug 3, 2026

ci(renovate): auto-update SHA256 checksums for tirith and cosign #5851

Merged

5 tasks

qodo-code-review Bot mentioned this pull request Aug 10, 2026

ci(vouch): add Slack notification for new vouch requests #6038

Merged

2 tasks

Navigation Menu

Uh oh!

ci/docs: deploy documentation site on Cloudflare with PR previews - #225

ci/docs: deploy documentation site on Cloudflare with PR previews#225
ifireball merged 2 commits into
fullsend-ai:mainfrom
ifireball:ifireball/site-cloudflare-workers

ifireball commented Apr 12, 2026 •

edited

Loading

Uh oh!

waynesun09 left a comment

Uh oh!

waynesun09 Apr 13, 2026

Uh oh!

waynesun09 Apr 13, 2026

Uh oh!

waynesun09 Apr 13, 2026

Uh oh!

waynesun09 Apr 13, 2026

Uh oh!

waynesun09 Apr 13, 2026

Uh oh!

waynesun09 Apr 13, 2026

Uh oh!

waynesun09 Apr 13, 2026

Uh oh!

ifireball commented Apr 14, 2026

Uh oh!

waynesun09 left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

ifireball commented Apr 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What changed

Uh oh!

waynesun09 left a comment

Choose a reason for hiding this comment

Uh oh!

waynesun09 Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

waynesun09 Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

waynesun09 Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

waynesun09 Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

waynesun09 Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

waynesun09 Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

waynesun09 Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

ifireball commented Apr 14, 2026

Uh oh!

waynesun09 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ifireball commented Apr 12, 2026 •

edited

Loading