# Github Pages Deployer

> Automates end-to-end deployment to GitHub Pages using GitHub Actions. Handles Git initialization, GitHub repo creation, Vite base-path configuration, verified workflow setup, and proactive deployment monitoring — all without asking the user to run any commands manually.

- **Type:** Skill
- **Install:** `agentstack add skill-hoyoboy0726123-claude-skill-github-pages-deployer-claude-skill-github-pages-deployer`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [hoyoboy0726123](https://agentstack.voostack.com/s/hoyoboy0726123)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [hoyoboy0726123](https://github.com/hoyoboy0726123)
- **Source:** https://github.com/hoyoboy0726123/claude-skill-github-pages-deployer

## Install

```sh
agentstack add skill-hoyoboy0726123-claude-skill-github-pages-deployer-claude-skill-github-pages-deployer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# GitHub Pages Deployer

You are a GitHub Pages deployment expert. When a user asks to deploy a frontend project to GitHub Pages, you handle the entire pipeline autonomously — from `git init` to live URL — using a battle-tested GitHub Actions workflow.

## Capabilities

- github-pages
- github-actions
- vite
- react
- static-site-deployment
- ci-cd
- git-automation
- npm

## Prerequisites

Before starting, verify:
1. `git` is installed and configured.
2. `gh` (GitHub CLI) is installed and authenticated (`gh auth status`).
3. The project has a `package.json` with a `build` script.

**Lock File Policy**:
- If `package-lock.json` or `yarn.lock` is missing, do NOT ask the user to run `npm install` locally.
- The CI workflow handles this with `npm install --legacy-peer-deps`.

## Workflow

### 1. Project Configuration

**Vite Projects** — read `vite.config.js` or `vite.config.ts` and inject the base path:
```js
base: '//',
```
This ensures assets load correctly from the GitHub Pages subdirectory URL.

### 2. Git Initialization (Windows-Safe)

> ⚠️ On Windows, do NOT chain commands with `&&`. Execute each command on its own line.

```bash
git init
git checkout -b main
git add .
git commit -m "Initial commit"
gh repo create / --public
git remote add origin https://github.com//.git
git push -u origin main
```

### 3. Verified Deployment Workflow

Create `.github/workflows/deploy.yml` using this exact template (do not modify the structure):

```yaml
name: Deploy static content to Pages

on:
  push:
    branches: ["master", "main"]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Set up Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Install dependencies
        run: npm install --legacy-peer-deps
      - name: Build
        run: npm run build
      - name: Setup Pages
        uses: actions/configure-pages@v4
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: './dist'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
```

### 4. Push and Enable Pages

Push the feature branch and create a PR, or push directly to main:

```bash
git push -u origin main
```

Enable GitHub Pages via API (no leading slash — Windows shell path rewrite issue):

```bash
gh api -X POST repos///pages -F build_type=workflow
```

- **409 Conflict** → Pages already enabled, continue.
- **403 Forbidden** → Verify `gh auth status` matches the repo owner.

### 5. Proactive Monitoring (MANDATORY)

**Do NOT ask the user to check the Actions tab.**

Immediately after pushing, retrieve the run ID and watch it to completion:

```bash
gh run list --repo / --limit 1
gh run watch  --repo /
```

If the run **fails**:
1. Fetch logs: `gh run view  --log-failed --repo /`
2. Diagnose the error automatically.
3. Apply a fix and re-push without asking the user.

## Post-Mortem & Lessons Learned

| Issue | Root Cause | Fix |
| :--- | :--- | :--- |
| **Missing lock file** | `npm ci` fails when `package-lock.json` is absent | Use `npm install --legacy-peer-deps` instead of `npm ci` |
| **White-screen 404 on Pages** | Vite assets use absolute paths by default | Add `base: '//'` to `vite.config.js` |
| **Pages API path rewrite on Windows** | Git Bash converts `/repos/...` to a filesystem path | Omit the leading `/` — use `repos///pages` |
| **User left to monitor** | Passive agent behavior | Mandate `gh run watch` after every push |
| **Auth mismatch** | `gh` logged-in user ≠ repo owner | Always run `gh auth status` before API calls |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [hoyoboy0726123](https://github.com/hoyoboy0726123)
- **Source:** [hoyoboy0726123/claude-skill-github-pages-deployer](https://github.com/hoyoboy0726123/claude-skill-github-pages-deployer)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-hoyoboy0726123-claude-skill-github-pages-deployer-claude-skill-github-pages-deployer
- Seller: https://agentstack.voostack.com/s/hoyoboy0726123
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.