One-Push Static Publishing

A free, low-maintenance way to host organized static HTML on a domain you already own, where “publish” is a single step driven by a coding agent — and access can be locked down later without rebuilding anything.

The problem it solves

You want to turn a folder of hand-built (or agent-built) HTML pages into real, shareable URLs — fast, repeatable, and cheap — without standing up a server, a CI system, or a paid hosting plan. You also want the publishing action to be simple enough that an AI coding agent (or a kid, or you in a VR headset) can do it with a single command. And you'd like the option, later, to put a login in front of a page without re-architecting.

This design uses two free services you may already touch — GitHub and Cloudflare — and glues them together with their native git integration. Nothing custom runs anywhere.

Components

1. A GitHub organization (free) with private repositories

A dedicated organization holds the publishing repos and nothing sensitive — no private source you care about lives in it. Each “space” (a themed collection of pages) is its own repository. Repos are kept private: the source, history, and config are not browsable, while the deployed site is public. Free GitHub orgs allow unlimited private repos.

The org is also where you set a token policy: require owner approval for fine-grained access tokens. That turns any new publish credential into a visible, approved event.

2. Cloudflare Pages (free) — the host and the hook

Each repo is connected once to a Cloudflare Pages project through Cloudflare's GitHub app. From then on, every push auto-deploys — that's the “hook.” For plain HTML there is no build command and no framework; the repo root is served directly. (Cloudflare's current dashboard may instead create a Worker with static assets at *.workers.dev rather than a Pages project at *.pages.dev — it connects to git, auto-deploys on push, serves raw files, and supports custom domains and Access the same way; everything here applies to either. This page runs on the Worker variant.) Relevant free-tier facts:

• Unlimited bandwidth and ~100 projects per account.
• Automatic SSL, atomic deploys, and instant one-click rollback to any previous deploy.
• Deploys fine from a private repo (the site is public; the source stays private).
• No commercial-use restriction.

3. A domain you own, with DNS on Cloudflare

When the domain's DNS is already managed by Cloudflare, attaching a custom subdomain to a Pages project creates the DNS record and provisions SSL automatically — no second console, no manual certificate. Each space gets a tidy subdomain, e.g. space.yourdomain.com. (If the domain lives elsewhere, you can still point a CNAME at the Pages project; you just lose the automatic, gating-ready integration.)

4. The publish action — a repo-local agent skill

Publishing is just git add + git commit + git push. To make it a single word for an agent, a small “publish” skill is stored inside the repo (e.g. under .claude/skills/). Because it travels with the repo, any machine that clones the repo gets the same publish behavior — no global setup. The skill typically: shows what changed and the exact live URL, asks for a yes/no confirmation, refuses if there is no index.html, and prints the URL after pushing.

5. A per-repo scoped credential

The machine that publishes holds a fine-grained personal access token scoped to exactly one repository, with permission limited to Contents: Read & Write, and an expiry (e.g. 90 days). It is stored in the operating system's credential store (Keychain on macOS, Credential Manager on Windows, a credential helper on Linux) — never in a file in the repo. If that machine is ever compromised, the blast radius is “write to one public-output repo, expiring soon,” with no path to anything else.

6. Cloudflare Access (free) — optional gating

Because the domain is already proxied through Cloudflare, you can put Cloudflare Access (Zero Trust, free up to 50 users) in front of any page or subdomain. It gates by email one-time-PIN or single sign-on (Google/Microsoft/etc.), per person, and is toggled in the dashboard — the static HTML never changes. Taking a page down or restricting it is a policy flip, not a redeploy.

How a publish flows

   author's machine                     GitHub (private org repo)            Cloudflare
  ┌──────────────────┐   git push      ┌───────────────────────┐  webhook   ┌──────────────────────┐
  │ edit index.html  │ ───────────────▶│  repo: your-space      │ ──────────▶│ Pages project build  │
  │ say "publish"     │  (scoped token) │  main branch           │            │ (no build; copy root)│
  │ → commit + push   │                 └───────────────────────┘            └──────────┬───────────┘
  └──────────────────┘                                                                  │ deploy (atomic)
                                                                                         ▼
                                                          public, with auto-SSL:  https://space.yourdomain.com/
                                                          (optionally gated by Cloudflare Access)
  

Total moving parts you run: zero. GitHub stores; Cloudflare builds and serves; the token only ever authorizes the push.

Repository layout

One repo per space. The root index.html is a landing page; each page/app/demo is its own folder with its own index.html, which maps to a clean path URL.

your-space/
├─ index.html            → https://space.yourdomain.com/
├─ first-thing/
│  └─ index.html         → https://space.yourdomain.com/first-thing/
├─ second-thing/
│  └─ index.html         → https://space.yourdomain.com/second-thing/
├─ CLAUDE.md             guidance for the agent working in this repo
├─ README.md
└─ .claude/
   └─ skills/
      └─ publish/
         └─ SKILL.md      the one-word "publish" skill (travels with the repo)
  

Recreate it from scratch

Generic steps. Replace your-org, your-space, and yourdomain.com with your own. An agent can run the gh/git parts; the Cloudflare and token steps are dashboard actions.

Note: Cloudflare's “Create” flow may produce either a Pages project (*.pages.dev) or a Worker with static assets (*.workers.dev). Both work identically here — the only difference is where you attach the custom domain in step 6: a Pages project uses its Custom domains tab; a Worker uses Settings → Domains & Routes.

gh repo create your-org/your-space --private --add-readme
# add an index.html landing page + one folder per page, each with its own index.html

git clone https://github.com/your-org/your-space.git
cd your-space
# edit a page, then:
git add -A && git commit -m "Publish" && git push origin main
# first push prompts for username + token; the OS credential store remembers it

Credential & isolation model

The security story is “smallest possible blast radius, per space”:

• One token per repo, scoped to that repo only, Contents R/W, with expiry. A leak grants write to one public-output repo for a limited time — nothing else.
• Separate spaces get separate tokens (and optionally separate orgs). A credential for one space cannot touch another.
• Private source, public output. The repo is private; only the rendered pages are public.
• No secrets in the repo. The token lives in the OS credential store, never in the working tree.
• Org approval gate for new tokens makes credential sprawl visible.

Why a fine-grained token rather than an SSH “deploy key”? A write deploy key is effectively admin on its repo, never expires, and isn't tied to a user. A fine-grained token is repo-scoped, permission-limited, and expires — better properties for an unattended or shared machine.

Why these choices

Cost

Limitations & caveats

• Static only. No server-side code. Dynamic behavior must be client-side or call an external API. (Cloudflare Functions/Workers can add server logic later if needed.)
• Public by default. Treat everything you push as public unless you've added Access. Don't commit secrets or anything confidential.
• The *.pages.dev name is globally shared and can't be renamed after creation — but it's only the origin URL; you share the custom domain.
• Free-tier limits exist (build counts, file sizes); generous for HTML, worth a glance for large media.