feat: auto deploy branches to github page

[adrienzheng-cb]

What changed? Why?

Adds an automated PR preview deployment system that publishes live previews of the documentation site and Storybook to GitHub Pages for every pull request, plus a landing page (preview-selector) to browse active previews.

How it works

• Authors opt in per-PR via the Preview deployment checkboxes below. Checking a box deploys that preview; unchecking it tears the preview down.
• Builds run in GitHub Actions and are published to the gh-pages branch under pr-<number>/…, served at:
  • Docs: https://coinbase.github.io/cds/pr-<number>/docs/
  • Storybook: https://coinbase.github.io/cds/pr-<number>/storybook/
• Everything lives side-by-side on the single gh-pages branch: / = preview selector, /pr-<number>/* = previews, /figma-audit/ = the Figma integration audit report.
• A single comment with the preview links is posted and kept up to date on the PR (older/duplicate bot comments are collapsed into one). Previews are removed automatically when the PR is closed.

Components

• .github/workflows/preview-deploy.yml — build + deploy previews on PR open/update/edit
• .github/workflows/preview-cleanup.yml — remove previews on PR close
• .github/workflows/preview-reap.yml — scheduled sweep that prunes previews for PRs that are no longer open
• .github/workflows/preview-manual-cleanup.yml — manual cleanup tool
• .github/workflows/figma.yml — the Figma audit now publishes into gh-pages:/figma-audit/ (see below) instead of taking over the whole Pages site
• apps/preview-selector/ — React app listing active previews (reads manifest.json)
• .github/scripts/* — manifest update/remove helpers

Coexisting with the Figma audit (single Pages site)

Previously the audit-figma-integrations job used actions/deploy-pages, which replaces the entire Pages site on every push to master — that clobbered all pr-<n>/* previews (they 404'd while / served the audit). It now publishes into gh-pages:/figma-audit/ using the same non-lossy orphan-commit + --force-with-lease flow as the preview deploy, touching only its own subtree. Both systems now share one branch without conflict.

Reliability & performance hardening

• Toggle without a commit: deploys react to PR-description edits; unchecking a box removes just that preview (or the whole PR directory when all boxes are cleared).
• Race-safe: the deploy re-reads the live checkbox state at push time, so a run superseded by a quick check→uncheck reconciles to the PR's current intent.
• Non-lossy concurrency: pushes to gh-pages use a re-fetch/re-apply loop with 8 attempts and exponential backoff (rather than GitHub's lossy concurrency queue), shared by both the preview and Figma-audit jobs.
• Caching: the Nx computation cache is persisted across runs, and docs/Storybook rebuilds are gated on nx affected (an app is only rebuilt when it changed or has no existing preview, so links never 404). BASE_URL / STORYBOOK_BASE_PATH are part of the Nx cache key so per-PR and production builds never collide.
• Storybook sub-path: preview builds use a relative asset base (via STORYBOOK_BASE_PATH) so they work under /pr-<n>/storybook/; the production Storybook build is unchanged.
• Static serving: a .nojekyll marker is written on every deploy so branch-served Pages publishes the compiled assets verbatim (no Jekyll processing).
• Storage guardrail: warns as gh-pages content approaches GitHub Pages' ~1GB limit.

One-time repo setup (required)

• GitHub Pages → Source = "Deploy from a branch" → gh-pages / (root). This system serves from the branch; the previous "GitHub Actions" source ignores the branch and 404s every preview.
• Because master's figma.yml must no longer run actions/deploy-pages, this PR needs to merge to master for the setup to stay stable — until then, any push to master re-runs the old audit job and re-takes the Pages site.

UI changes

No component/visual changes. The deliverable is the preview tooling itself — see the deployed preview links in the PR comment once the workflow runs.

Testing

How has it been tested?

• Unit tests
• Interaction tests
• Pseudo State tests
• Manual - Web (docs + Storybook previews)
• Manual - Android (Emulator / Device)
• Manual - iOS (Emulator / Device)

Testing instructions

1. With a preview box checked, confirm the workflow builds and comments docs/Storybook links, and the pages load.
2. Uncheck a box (no new commit) and confirm that preview is removed and the comment updates; uncheck both to confirm the whole PR directory is removed.
3. Push a new commit and confirm the comment updates in place (no new duplicate comments).
4. Close the PR and confirm previews are cleaned up.
5. Confirm the Figma audit is reachable at https://coinbase.github.io/cds/figma-audit/ after a master build, and that it does not disturb / or /pr-<n>/*.

Preview deployment

Check to deploy previews for this PR. Leave unchecked to skip.

• Deploy documentation preview
• Deploy Storybook preview

Illustrations/Icons Checklist

Not applicable — this PR does not change files under packages/illustrations/** or packages/icons/**.

• verified visreg changes with Terran (include link to visreg run/approval)
• all illustration/icons names have been reviewed by Dom and/or Terran

Change management

type=routine
risk=low
impact=sev5

automerge=false

[hcopp]

Thing to keep in mind

• We should see if we can set gh_pages to be a protected branch
• We need to test this with an outside contributor (such as Sam)

[cb-heimdall]

🟡 Heimdall Review Status

Requirement	Status	More Info
Reviews	🟡 0/1	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 1 Global minimum 0 Max 1 1 1 if commit is unverified 0 Sum 1
CODEOWNERS	🟡 See below

🟡 CODEOWNERS

Code Owner	Status	Calculation
ui-systems-eng-team	🟡 0/1	Denominator calculation Additional CODEOWNERS Requirement Show calculation Sum 0 0 From CODEOWNERS 1 Sum 1

[github-actions]

🚀 Previews Deployed

Your previews are ready!

📄 Documentation: View Docs →
📚 Storybook: View Storybook →

---

📝 Updated: 2026-07-31T17:36:49.788Z
🔨 Commit: 30e46f517f05584ebd36db180b8e79dd526bf5c4

Previews are removed when the PR is closed or all checkboxes are unchecked.
To change what's deployed, edit the checkboxes in the PR description.