158 lines
8.4 KiB
Markdown
158 lines
8.4 KiB
Markdown
---
|
||
name: publish-site
|
||
description: Versioned site deploys to GitHub/Cloudflare/Netlify Pages.
|
||
version: 1.0.0
|
||
author: Hermes Agent (Nous Research)
|
||
license: MIT
|
||
platforms: [linux, macos, windows]
|
||
metadata:
|
||
hermes:
|
||
tags: [publish, deploy, hosting, github-pages, cloudflare-pages, netlify, static-site, versioning, rollback, web-development]
|
||
category: web-development
|
||
---
|
||
|
||
# Publish Site
|
||
|
||
Take a website, dashboard, or web app the user built (or you built for them) and put it online on infrastructure the user owns — GitHub Pages by default, Cloudflare Pages or Netlify when they need more. The discipline: preview locally for sign-off, version every deploy with a git tag, deploy through a provider ladder, verify the live URL with a real HTTP check, and keep rollback one command away.
|
||
|
||
This skill covers static sites and SPA build output (plain HTML/CSS/JS, or the `dist/`/`build/` folder from Vite/Next-export/Astro/etc.). It does not cover server-side runtimes — for throwaway serverless deploys with zero account setup, use the `cloudflare-temporary-deploy` optional skill instead.
|
||
|
||
## When to Use
|
||
|
||
Load this skill when the user asks to:
|
||
|
||
- **Put a site online** — "publish this", "host this somewhere", "give me a link I can share"
|
||
- **Deploy a dashboard, report, portfolio, docs site, or prototype** you just generated
|
||
- **Update an already-published site** with new content (redeploy = new version)
|
||
- **Roll back** a bad deploy to the previous version
|
||
- **Pick a host** — they don't care where, they just want a URL
|
||
|
||
## Prerequisites
|
||
|
||
At least ONE authenticated provider CLI (check in this order):
|
||
|
||
- **GitHub Pages (default):** `gh auth status` succeeds. Needs `git` too.
|
||
- **Cloudflare Pages:** `wrangler whoami` succeeds (or `CLOUDFLARE_API_TOKEN` is set). Install: `npm i -g wrangler` or use `npx wrangler@latest`.
|
||
- **Netlify (fallback):** `netlify status` succeeds. Install: `npm i -g netlify-cli`.
|
||
|
||
Plus:
|
||
|
||
- A directory of static output to publish (site root or a `dist/`/`build/` folder). If the project needs a build step, run it first and publish the output directory, never the source.
|
||
- For local preview sharing: `cloudflared` (optional — `python3 -m http.server` covers local-only preview).
|
||
|
||
## How to Run
|
||
|
||
All commands below run via the `terminal` tool from the site's project directory. The pipeline is always the same five moves:
|
||
|
||
1. Build → 2. Preview for sign-off → 3. Commit + tag (version-before-deploy) → 4. Deploy via the provider ladder → 5. Verify the live URL with `curl` and report it.
|
||
|
||
## Quick Reference
|
||
|
||
| Step | Command |
|
||
|---|---|
|
||
| Local preview | `python3 -m http.server 8080 --directory dist` |
|
||
| Shareable preview | `cloudflared tunnel --url http://localhost:8080` |
|
||
| Version a deploy | `git add -A && git commit -m "deploy: <what>" && git tag deploy-YYYYMMDD-HHMM` |
|
||
| GitHub Pages (branch mode) | `git subtree push --prefix dist origin gh-pages` |
|
||
| Enable Pages on repo | `gh api repos/{owner}/{repo}/pages -X POST -f 'source[branch]=gh-pages' -f 'source[path]=/'` |
|
||
| Cloudflare Pages | `npx wrangler@latest pages deploy dist --project-name <name>` |
|
||
| Netlify | `netlify deploy --prod --dir dist` |
|
||
| Rollback | `git checkout <previous-tag> -- . && redeploy` (or provider dashboard) |
|
||
| Verify live | `curl -sS -o /dev/null -w '%{http_code}' <url>` → expect `200` |
|
||
|
||
## Procedure
|
||
|
||
### 1. Build and preview locally
|
||
|
||
Build if needed (`npm run build`, etc.) and identify the output directory. Serve it:
|
||
|
||
```bash
|
||
python3 -m http.server 8080 --directory dist
|
||
```
|
||
|
||
For a shareable preview link (user on another machine, or you want their sign-off before going live), open a quick tunnel in a background `terminal` session:
|
||
|
||
```bash
|
||
cloudflared tunnel --url http://localhost:8080
|
||
```
|
||
|
||
Give the user the `https://*.trycloudflare.com` URL and get sign-off before deploying. Kill the tunnel afterwards.
|
||
|
||
### 2. Version before deploy — no exceptions
|
||
|
||
Every deploy must come from a git commit, so every deploy is reproducible and rollback is trivial.
|
||
|
||
```bash
|
||
git init 2>/dev/null; git add -A
|
||
git commit -m "deploy: <short description>"
|
||
git tag "deploy-$(date +%Y%m%d-%H%M)"
|
||
```
|
||
|
||
If the project already has a repo, just commit + tag. Never deploy uncommitted files.
|
||
|
||
### 3. Deploy — provider ladder
|
||
|
||
**Rung 1 — GitHub Pages (default: free, zero extra accounts if `gh` is authed):**
|
||
|
||
```bash
|
||
gh repo create <name> --public --source . --push # skip if repo exists
|
||
git subtree push --prefix dist origin gh-pages # publish build output
|
||
gh api "repos/{owner}/<name>/pages" -X POST \
|
||
-f 'source[branch]=gh-pages' -f 'source[path]=/' # first time only
|
||
```
|
||
|
||
Site appears at `https://<owner>.github.io/<name>/`. If the site is the repo root (no build dir), push `main` and set Pages source to `main` instead of using subtree. For build-step projects that will redeploy often, prefer the official `actions/deploy-pages` workflow so pushes auto-publish.
|
||
|
||
**Rung 2 — Cloudflare Pages (when the user wants a custom domain, redirects/headers, or Functions):**
|
||
|
||
```bash
|
||
npx wrangler@latest pages deploy dist --project-name <name>
|
||
```
|
||
|
||
First run creates the project and prints the `https://<name>.pages.dev` URL. Custom domains attach via the Cloudflare dashboard (Pages → project → Custom domains).
|
||
|
||
**Rung 3 — Netlify (fallback, or when the user already lives there):**
|
||
|
||
```bash
|
||
netlify deploy --prod --dir dist
|
||
```
|
||
|
||
`netlify deploy --dir dist` (no `--prod`) gives a draft URL — useful as a second preview stage.
|
||
|
||
### 4. Rollback
|
||
|
||
Rollback = redeploy a previous tag. Never hand-edit live output.
|
||
|
||
```bash
|
||
git checkout deploy-<previous> -- . # or: git checkout deploy-<previous>; rebuild
|
||
# then rerun the same deploy command from step 3
|
||
```
|
||
|
||
Cloudflare Pages and Netlify also keep per-deploy history in their dashboards ("Rollback to this deploy"), which is faster when the CLI isn't handy.
|
||
|
||
### 5. Secrets and environment variables
|
||
|
||
- **NEVER commit secrets, API keys, or `.env` files** — they'd be public on Pages hosting. Check with `git status` before the first commit and keep `.env*` in `.gitignore`.
|
||
- Runtime env vars belong in the provider's dashboard: Cloudflare Pages → Settings → Environment variables; Netlify → Site settings → Environment variables. GitHub Pages is static-only — no server env; anything embedded in the bundle is public by definition. Warn the user if their build inlines a key.
|
||
|
||
## Pitfalls
|
||
|
||
- **SPA routes 404 on GitHub Pages.** Pages has no rewrite rules. Copy `index.html` to `404.html` in the output dir (`cp dist/index.html dist/404.html`) so client-side routing recovers. Cloudflare Pages and Netlify handle SPAs via `_redirects` (`/* /index.html 200`).
|
||
- **GitHub Pages build lag.** The site can take 1–10 minutes to appear after the first enable, and ~1 minute per subsequent push. Don't declare failure on the first 404 — poll `curl` a few times before investigating.
|
||
- **Case-sensitive paths.** Pages hosts are case-sensitive Linux; a site that worked on macOS/Windows can 404 on assets referenced as `Logo.PNG` but committed as `logo.png`. Grep the HTML for mismatched casing when an asset 404s.
|
||
- **Project-page base path.** `https://<owner>.github.io/<name>/` serves under `/<name>/` — absolute asset URLs like `/app.js` break. Use relative paths or set the build tool's base (`vite build --base=/<name>/`).
|
||
- **`wrangler` auth flow needs a browser.** `wrangler login` opens OAuth; in a headless session prefer `CLOUDFLARE_API_TOKEN` (user creates it at dash.cloudflare.com → API Tokens) and never echo the token into logs.
|
||
- **DNS propagation on custom domains.** New CNAMEs can take minutes to hours. Verify against the provider's default URL (`*.pages.dev`, `*.netlify.app`, `*.github.io`) first, then check the custom domain separately — don't conflate the two failures.
|
||
- **Deploying source instead of build output.** Publishing the repo root when the real site lives in `dist/` yields a directory listing or raw JSX. Always confirm the output dir contains an `index.html`.
|
||
|
||
## Verification
|
||
|
||
Do NOT report success from the deploy log alone. Before telling the user anything:
|
||
|
||
1. `curl -sS -o /dev/null -w '%{http_code}' <live-url>` returns `200` (retry over ~2 minutes for a first GitHub Pages deploy).
|
||
2. `curl -sS <live-url> | head -30` shows the expected `index.html` content — optionally confirm markup with `web_extract` on the live URL.
|
||
3. For SPAs, also curl one deep route (e.g. `/about`) and confirm it returns `200`, not `404`.
|
||
4. `git tag --list 'deploy-*'` shows the tag for this deploy.
|
||
|
||
Then report the live URL to the user, along with the deploy tag they can roll back to.
|