Deploy static frontend projects to GitHub Pages. Use when the user mentions deploying to GitHub, publishing a website to GitHub Pages, hosting static sites, or making HTML/CSS/JS projects publicly accessible online. Validates that the project is static (no backend code) before deployment.
Deploy static frontend projects to GitHub Pages, making them accessible at https://<username>.github.io/<repo-name>/.
Verify environment before proceeding:
gh --version # GitHub CLI required
gh auth status # Must be authenticated
git --version # Git required
If not installed: https://cli.github.com/ → then gh auth login
Check if project is deployable:
# Must have index.html
ls index.html docs/index.html dist/index.html build/index.html 2>/dev/null
# Must NOT have backend files (if found, STOP)
ls server.js app.py main.go *.php 2>/dev/null
If backend files detected: Do NOT proceed. Explain GitHub Pages only supports static sites. Suggest Vercel, Netlify, or Railway instead.
cd <project-path>
[ ! -d .git ] && git init && git add . && git commit -m "Initial commit"
gh repo create <repo-name> --public --source=. --push
Or for existing repo:
git remote add origin https://github.com/<username>/<repo-name>.git
git branch -M main
git push -u origin main
GITHUB_USER=$(gh api user -q .login)
gh api repos/$GITHUB_USER/<repo-name>/pages -X POST \
-H "Accept: application/vnd.github+json" \
-f source='{"branch":"main","path":"/"}'
gh api repos/$GITHUB_USER/<repo-name>/pages --jq '.html_url'
| Error | Solution |
|---|---|
| Pages already enabled | Use -X PUT instead of -X POST |
| Not authenticated | gh auth login |
| No index.html | Cannot deploy; static site requires index.html |
Success:
✅ Deployed successfully!
📦 Repository: https://github.com/<username>/<repo-name>
🌐 Live URL: https://<username>.github.io/<repo-name>/
Rejection:
❌ Cannot deploy to GitHub Pages
This project contains backend code (server.js).
Alternatives: Vercel, Netlify, Railway
For existing sites, just push:
git add . && git commit -m "Update" && git push