/github-pages-publish

name: github-pages-publish
description: "Publish or update a static site (gh-pages) on GitHub Pages via GitHub Actions in any repo: text or pre-built HTML in, workflow set up, live URL verified. Don't use for CI test pipelines, framework/SSG builds, or Netlify/Vercel hosting."
license: MIT
effort: high
dependencies:
  - frontend-design
metadata:
  version: 1.0.2
  author: "Luong NGUYEN <luongnv89@gmail.com>"

GitHub Pages Publish

Put a website live on GitHub Pages and hand back a URL that was checked live. The input is the content (text, one HTML file, or a folder of ready files) and the target repo, which can differ from the repo the user is working in. The skill creates or repairs a GitHub Actions deploy workflow, sets Pages to deploy from Actions, pushes to the default branch, and proves the live site serves the committed bytes. Automate every step. Stop only at a confirmation gate.

Terms used throughout:

• **target repo**: `owner/name` that hosts the site. A bare `name` means the gh user's account.
• **content**: the files to publish, staged in `<work>/content/` before anything is pushed.
• **workspace**: the checkout that receives the commit. It is the current checkout (in-place) or a clone in `<work>/repo/`.
• **site folder**: the folder inside the workspace that Pages deploys: `.`, `docs`, or the user's choice.
• **confirmation gate**: one of the questions listed in Step 2. Nothing else stops the run.
• **pre-authorized**: the request already answers a gate ("create it if needed", "make it public"). State the answer in one line and continue.
• **live check**: `verify` passes, which means every checked file at the Pages URL matches the committed file byte for byte.
• **run log**: `.pages-publish/run-<UTC>.md` in the current directory. Every step appends one row.

`P` means `python3 <skill>/scripts/pages_publish.py`. Each subcommand prints JSON. Exit 1 means a check failed, 2 means bad input or a missing tool, and 3 means a conflict that needs the user. On a nonzero exit, read the `error:` and `fix:` lines on stderr, then use `references/troubleshooting.md`. Load a `references/` file only at the step that names it, to save the agent's context budget.

When to Use

Use when someone wants a website, page, or set of HTML files published or updated on GitHub Pages, in the current repo or another one. Not for CI test or lint pipelines (`devops-pipeline`), release tagging (`ship`), designing a page without publishing it (`frontend-design`), building a framework or site-generator project (publish its built output instead), custom-domain DNS setup, or hosting outside GitHub Pages.

Step 0: Select the branch

| Condition | Branch | |---|---| | The request says "dry run", "plan only", or "don't push" | **Dry run**: run Steps 1, 3, 4 and 5 in a clone (never in-place, never the Repo Sync on the user's checkout) with `--dry-run`. Create, change, and push nothing. Report `DRY-RUN` | | The content is text: inline in the request, or a `.md` or `.txt` file | **Text**: Step 3 builds the page with `frontend-design` | | The content is one `.html` file, or a folder that holds HTML | **Ready files**: Step 3 stages the files as given | | No content or no target repo can be found in the request | Ask for the missing item. Do nothing else |

Defaults: if the request names no target repo, use the current checkout's `origin`. If the current directory is not a GitHub checkout, ask for the target repo.

After each step, append one run-log row with `P log --file <log> --step "<N name>" --status pass|fail|skip|info|ask --msg "<result>" --cmd "<command>"`, then print a Step Completion Report: `√`/`×` rows tied to a command, file, or count, then `Result: PASS | FAIL | PARTIAL`. Log a gate as `ask` when it is asked or pre-authorized, then log the answer as `pass` (yes) or `fail` (no).

Step 1: Log and preflight (read-only)

1. Run `P log-init --request "<one-line request>"`. Record the `log` path. 2. Run `P preflight --repo <target>`. The command only reads. 3. If `blockers` is not empty, log each blocker, report BLOCKED with the blocker's `fix`, and stop. 4. Keep the JSON. Later steps read `target`, `pages`, `workflows`, `local`, and `scope_gaps` from it. 5. Set `work` to `${TMPDIR:-/tmp}/github-pages-publish/<owner>-<name>-<UTC stamp>`. 6. Read the site type from `target.project_site`, and the URL the site will have from `target.expected_url` (a dry run reports this one, labeled "expected, not checked"). A project site is served under `/<name>/`. A user site (`<owner>.github.io`) or a custom-domain site is served at the domain root.

Bar: `preflight` exited 0 and `blockers` is empty.

Step 2: Resolve the confirmation gates

Ask only for the gates that `preflight` returned. Put all of them in one message. If the run is pre-authorized for a gate, log `ask` with the request's wording and do not ask.

| Gate id | Ask | Action on yes | Action on no | |---|---|---|---| | `create-repo` | "Create public repo `<owner>/<name>`?" | Create it in Step 4 | BLOCKED | | `private-repo` | "`<repo>` is private. Pages sites are public. Make the repo public (recommended), keep it private (needs a paid plan), or stop?" | Public: `gh repo edit <repo> --visibility public --accept-visibility-change-consequences`. Keep private: continue, and a 422 from `configure` means BLOCKED | BLOCKED | | `enable-actions` | "Actions is disabled on `<repo>`. Enable it?" | `gh api -X PUT repos/<repo>/actions/permissions -F enabled=true` | BLOCKED |

A command named in a gate's `fix` (`gh auth refresh ...`) is interactive: ask the user to run it (in Claude Code, with the `!` prefix), then re-run `preflight`. A dry run lists the gates it would ask and changes nothing. Bar: every gate has a logged answer, or the run ended BLOCKED.

Dependency Preflight (mandatory)

This skill optionally invokes `frontend-design`, declared in frontmatter `dependencies`. It is used on the Text branch only. Before Step 3:

command -v asm >/de