GitHub Pages One-Click Deployment

Zero-config deployment of static websites to GitHub Pages with full automation.

Core Principle

Detect → Install → Configure → Deploy → Verify. Never ask users for information you can detect automatically.

When to Use

• "部署一个网站到GitHub Pages"
• "一键部署XX网页"
• "帮我做个网站并发布"
• Any request combining web content creation + public hosting

Do NOT use for: Backend apps, private repos, or dynamic web apps requiring servers.

Red Flags - STOP Asking, START Detecting

All of these mean: You're being too cautious. Automate more.

Workflow

digraph deploy_flow {
    rankdir=TB;
    node [shape=box];
    
    start [label="User Request", shape=doublecircle];
    detect [label="1. Detect\n(Git, gh, auth)"];
    install [label="2. Auto-Install"];
    auth [label="3. Setup Auth"];
    repo [label="4. Create Repo"];
    generate [label="5. Generate HTML"];
    deploy [label="6. Push & Enable"];
    verify [label="7. Verify URL"];
    done [label="Return Live URL", shape=doublecircle];
    
    start -> detect -> install -> auth -> repo -> generate -> deploy -> verify -> done;
}

Implementation

1. Detect Environment (Silent)

git --version 2>/dev/null || NEED_GIT=1
gh --version 2>/dev/null || NEED_GH=1
gh auth status 2>/dev/null || NEED_AUTH=1
GH_USER=$(gh api user --jq .login 2>/dev/null)

Never ask user for this. Detect it yourself.

2. Auto-Install Tools

# macOS: brew install git gh
# Linux: apt-get install git gh
# Windows: winget install Git.Git GitHub.cli

Do NOT ask "你装了Git吗？" - just install it.

3. Setup Authentication

gh auth login --web --git-protocol https

Use browser OAuth, NOT SSH keys. Users don't understand SSH.

4. Create Repository

REPO_NAME="${GH_USER}.github.io"

# Handle conflicts automatically
if gh repo view "$GH_USER/$REPO_NAME" &>/dev/null; then
  REPO_NAME="${GH_USER}-site-$(date +%s)"
fi

gh repo create "$REPO_NAME" --public --clone

Don't ask "仓库已存在，怎么办？" - auto-create project repo.

5. Generate HTML

Use Tailwind CSS CDN. Always responsive. See scripts.sh for template.

6. Deploy with Retry

git add . && git commit -m "Initial deployment"

# Retry 3x if push fails
for i in {1..3}; do
  git push -u origin main && break || sleep 2
done

# Enable Pages for project repos
gh api -X POST "repos/$GH_USER/$REPO_NAME/pages" \
  -f source[branch]=main -f source[path]=/

7. Verify Deployment

# Poll until HTTP 200 (max 3 min)
for i in {1..36}; do
  curl -s -o /dev/null -w "%{http_code}" "$URL" | grep -q "200" && break
  sleep 5
done

Do NOT return URL without verifying it's live.

Common Mistakes

Rationalization Table

Success Criteria

Deployment is complete when:

• ✅ User receives working HTTPS URL
• ✅ URL returns HTTP 200 (verified by curl)
• ✅ Content matches user's request
• ✅ Responsive design works on mobile
• ✅ User did NOT manually run commands
• ✅ User did NOT answer technical questions

If any failed, deployment is incomplete.

Supporting Files

• scripts.sh - Complete automation scripts and HTML template