flow-cloudflare-pages

Files (5)

• SKILL.md
• deployment-pruning.md · references/
• env-vars-and-build.md · references/
• prune-cf-deployments.test.ts · templates/
• prune-cf-deployments.ts · templates/

SKILL.md (first lines)

# Goal

Provide deployment-pruning, preview/prod env handling, SPA fallback, and
CORS guidance for projects deployed to Cloudflare Pages — without bringing
in the full 8-skill cloudflare plugin. Manually invoked only; the skill
matcher does not auto-load this skill on file/path signals.

# When to Use

- Bulk-pruning preview / production deployments that have accumulated.
- Configuring preview vs production env vars on a Cloudflare Pages project.
- Setting up SPA fallback for SvelteKit `@sveltejs/adapter-static` (or any
  SPA) on Pages.
- Configuring CORS allowlist to handle preview deployment URLs.
- User invokes via `/flow-cloudflare-pages`, 'use the cloudflare-pages skill',
  or 'prune cf deployments' — manual invocation only (the matcher does not
  auto-load this skill).

# When NOT to Use

- Cloudflare Workers (non-Pages) — defer to the official `cloudflare:wrangler`
  skill from the cloudflare plugin (`cloudflare@claude-plugins-official`).
- KV / R2 / D1 / Durable Objects / Workers AI / Vectorize / Hyperdrive /
  Queues / Workflows / Pipelines / Containers / Secrets Store — defer to
  `cloudflare:wrangler`.
- Pages Functions (`_worker.js` Pages Functions, advanced routing) — beyond
  a brief callout, defer to `cloudflare:wrangler`.
- Account-level setup (creating accounts, billing, Zero Trust) — out of
  scope.

# Context

- Cloudflare Pages exposes no native deployment-retention CLI/API today
  (the dashboard 'Deployment retention' toggle has been historically
  unreliable). Pruning must be scripted.
- Wrangler's `pages deployment list` and `pages deployment delete` commands
  handle simple cases but refuse aliased / active deployments — the CF
  REST API
  (`DELETE /accounts/{account_id}/pages/projects/{project_name}/deployments/{deployment_id}?force=true`)
  is required for those.
- Build env vars prefixed `VITE_*` or `PUBLIC_*` are baked into the bundle
  at build time — changing them requires a redeploy.
- Preview deployments get dynamic URLs (`https://<hash>.<project>.pages.dev`)
  that need wildcard handling in CORS allowlists.

## 1. Deployment Pruning

This is the originating concern this skill exists to address.

For a few stale deployments, use Wrangler:

```bash
wrangler pages deployment list --project-name <your-project>
wrangler pages deployment delete <deployment-id> --project-name <your-project>
```

For bulk-pruning on a schedule (e.g. nightly cleanup of preview deployments
older than 30 days), call the reusable workflow from a wrapper workflow in
your repo:

```yaml
# .github/workflows/prune-cf-pages.yml
name: prune-cf-pages

on:
  schedule:
    - cron: "0 7 * * *" # 07:00 UTC daily
  workflow_dispatch:

jobs:
  prune:
    permissions:
      contents: read
    uses: gavingolden/flow/.github/workflows/cloudflare-pages-prune.yml@<sha>
    with:
      project: my-project
      older_than_days: 30
      branch: "!main" # optional; omit to match all branches
      dry_run: false # default; permanently deletes deployments — set true for a dry-run validation pass
    secrets:
      CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
      CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
      WORKFLOW_REPO_TOKEN: ${{ secrets.WORKFLOW_REPO_TOKEN }} # optional; see below
```

The SHA in `uses:` pins both the workflow contract AND the prune script —
the workflow's own `actions/checkout` step fetches `gavingolden/flow` at
the same SHA the caller resolved, so the script the workflow runs always
matches the workflow's own version. The workflow resolves its own SHA
from `job.workflow_ref` (which carries the `@<sha>` suffix the caller
pinned), so callers never have to pass flow's SHA explicitly — just keep
the `@<sha>` pin on `uses:` up to date. To upgrade, bump the SHA;
consumers never re-vendor.

`WORKFLOW_REPO_TOKEN` is only required in the **private→private cross-repo
case**: when your calling repo is private _and_ `gavingolden/flow` is
private to your account/org, the default `GITHUB_TOKEN` is scoped to the
caller's repo and cannot fetch a sibling private repo's source, so the
`actions/checkout` step that pulls `gavingolden/flow` will 404. Pass a
fine-grained PAT (or GitHub App installation token) with `Contents:Read`
on `gavingolden/flow` to resolve. Omit (or leave unset) when the caller
is a public repo, when `gavingolden/flow` is public, or when the caller
_is_ `gavingolden/flow` itself — in those cases the default token already
has read access. (Note that the _revision_ being checked out is still
resolved from `job.workflow_ref` regardless of which token does the
fetch — the token decides whether the fetch is allowed, not which SHA is
fetched.)

Inputs:

- `project` (string, required) — Cloudflare Pages project name.
- `older_than_days` (number, required) — cutoff in days; passed to the
  script as `--older-than <N>d`.
- `branch` (string, optional, default `''`) — single glob passed to the
  script's `--branch` flag. Supports positive (`feat/*`) or negative
  (`!main`) globs. Empty string omits `--branch` so the script matches
  all branches.
- `dry_run` (boolean, optional, default `false`) — **permanently deletes**
  Cloudflare Pages deployments matched by the filter via `DELETE ?force=true`

From gavingolden/flow, MIT.

More from gavingolden/flow