gh-pages-deploy skill

Overview

This skill automates deploying static or interactive frontend content to GitHub Pages using the GitHub CLI. It guides you through repository initialization, creating a public repo, enabling Pages, and verifying the live site URL. Use it to quickly publish demos, portfolios, docs, or browser-based projects with minimal CLI work.

How this skill works

The skill uses the GitHub CLI (gh) and standard Git commands to initialize or use an existing repo, push content to GitHub, and call the Pages API to enable a site from the repository root or /docs. It can run a single quick-deploy flow that creates the repo, pushes the current branch, enables Pages, and returns the public URL. It also includes commands to check deployment status and troubleshoot build problems.

When to use it

• Publish a demo, prototype, or interactive visualization so others can open it in a browser.
• Share a landing page, documentation site, or portfolio with a public URL quickly.
• Make a browser-based tool or game accessible without hosting infrastructure.
• Deploy an updated static site after local changes and verify the build.
• Expose a /docs folder or project root as the Pages source for versioned docs.

Best practices

• Ensure gh is installed and authenticated (gh auth login) before running deploy commands.
• Keep index.html at the chosen source root (root or /docs) to avoid 404s.
• Use a public repository for free GitHub Pages or verify billing/features for private repo publishing.
• Commit and test locally (open index.html) before pushing to reduce build failures.
• Check GitHub Actions or Pages builds for error logs when a deploy fails.

Example use cases

• One-command deploy of a prototype site from your local folder to https://<username>.github.io/<repo>/.
• Publish project documentation by placing files in /docs and enabling Pages from that path.
• Host a static single-page app (SPA) or interactive visualization without setting up servers.
• Create and share a portfolio or landing page after a final commit and push.
• Automate regular updates by scripting git add/commit/push and re-triggering the Pages build.

FAQ