GitHub Pages 一键部署工具 - 自动检测项目类型并生成工作流

GitHub Pages by alfredang/skills

1 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/alfredang/skills --skill 'GitHub Pages'

开发自动化开发运维

🇨🇳中文介绍

GitHub Pages 部署

命令

/github-page 或 github-page

关键词

github pages, deploy pages, static site, gh-pages, github actions, deploy website, host website, github hosting, deploy static, pages deploy, free hosting, github site, publish site, deploy html, deploy react to github

描述

无需手动配置，即可将任何项目部署到 GitHub Pages。自动检测项目类型，生成正确的 GitHub Actions 工作流，通过 API 在仓库中启用 GitHub Pages 和 Actions，并提供一个实时 URL。

执行

此技能使用 Claude Code 订阅计划 运行。请勿使用按量付费的 API 密钥。所有 AI 操作都应在具有活动订阅的 Claude Code CLI 环境中执行。

响应

我将帮助您部署到 GitHub Pages！

工作流程包括：

步骤	描述
预检	验证 `gh` CLI、git 远程仓库和仓库访问权限

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

阶段 2：检测项目类型

分析项目以确定构建命令和输出目录。

指示器	项目类型	构建命令	输出目录
`vite.config.*`	Vite (React/Vue/Svelte)	`npm install && npm run build`	`./dist`
`next.config.*`	Next.js (静态导出)	`npm install && npm run build`	`./out`
`angular.json`	Angular	`npm install && npm run build`	`./dist/<project>`
`package.json` 包含 `build` 脚本	Node.js 项目	`npm install && npm run build`	`./dist` 或 `./build`
根目录下的 `index.html`	静态 HTML	无	`./`
`public/index.html`	public/ 目录下的静态文件	无	`./public`
`requirements.txt` + `mkdocs.yml`	MkDocs	`pip install -r requirements.txt && mkdocs build`	`./site`
以上均不符合	未知	询问用户	询问用户

2.2 特定框架配置

Vite 项目 — 确保在 vite.config.* 中设置了 base：

export default defineConfig({
  base: '/<REPO>/',
})

如果未设置 base，请通知用户 — 没有它，站点的资源路径将会损坏。

Next.js 项目 — 确保 next.config.* 中包含 output: 'export'：

const nextConfig = {
  output: 'export',
  basePath: '/<REPO>',
}

2.3 Node.js 版本检测

检查 .nvmrc、.node-version 或 package.json 中的 engines.node，以在工作流中设置正确的 Node.js 版本。如果未指定，则默认为 20。

阶段 3：生成 GitHub Actions 工作流

创建 .github/workflows/deploy-pages.yml：

3.1 静态 HTML (无构建步骤)

name: Deploy to GitHub Pages

on:
  push:
    branches: [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: Setup Pages
        uses: actions/configure-pages@v5

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v4
        with:
          path: '.'

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

3.2 Node.js 项目 (React/Vite/Next.js/Angular)

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

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

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '<NODE_VERSION>'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

      - name: Setup Pages
        uses: actions/configure-pages@v5

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v4
        with:
          path: '<OUTPUT_DIR>'

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

将 <NODE_VERSION> 和 <OUTPUT_DIR> 替换为从阶段 2 检测到的值。

3.3 创建工作流文件

mkdir -p .github/workflows

将适当的工作流 YAML 写入 .github/workflows/deploy-pages.yml。

阶段 4：启用 GitHub Pages 和 Actions (自动配置)

4.1 提交并推送工作流

git add .github/workflows/deploy-pages.yml
git commit -m "$(cat <<'EOF'
ci: add GitHub Pages deployment workflow

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"
git push origin main

重要： 始终添加特定文件。切勿使用 git add . 或 git add -A。

4.2 通过 API 启用 GitHub Pages

首先，检查 Pages 是否已启用：

gh api "/repos/$OWNER/$REPO/pages" 2>/dev/null

如果未启用 (404 响应)，则创建它：

gh api -X POST "/repos/$OWNER/$REPO/pages" -f build_type=workflow

如果已启用但使用不同的源，则更新它：

gh api -X PUT "/repos/$OWNER/$REPO/pages" -f build_type=workflow

gh workflow enable deploy-pages.yml

4.4 触发初始部署 (如果推送未触发)

gh workflow run deploy-pages.yml

阶段 5：验证和报告

5.1 检查工作流运行

等待几秒钟，然后检查：

gh run list --workflow=deploy-pages.yml --limit 1

=== GitHub Pages Deployment ===

Workflow: .github/workflows/deploy-pages.yml (created)
GitHub Pages: ENABLED (source: GitHub Actions)
GitHub Actions: ENABLED

Deployment URL: https://<OWNER>.github.io/<REPO>/
Workflow runs: https://github.com/<OWNER>/<REPO>/actions

Status: Deploying... (check Actions tab for progress)

5.3 如果发生错误

Pages API 返回 409 (冲突)：

Pages 可能已配置了分支源
使用 PUT 而不是 POST 进行更新

工作流未触发：

确保分支名称匹配 (main 与 master)

检查 Actions 是否在仓库级别已启用：

gh api -X PUT "/repos/$OWNER/$REPO/actions/permissions" -f enabled=true

检查工作流运行日志：
```
gh run view --log
```
常见问题：Vite 缺少 base 配置，Next.js 缺少 output: 'export'

自动检测项目类型 (静态 HTML、React、Vite、Next.js、Angular、MkDocs)
为项目生成正确的 GitHub Actions 工作流
通过 API 启用以 Actions 为源的 GitHub Pages
自动在仓库上启用 GitHub Actions
触发初始部署
支持自定义构建命令和输出目录
从项目配置中检测 Node.js 版本

运行 /github-page 后：

检查 Actions 选项卡：https://github.com/<OWNER>/<REPO>/actions
等待第一次部署完成 (通常 1-2 分钟)
访问您的实时站点：https://<OWNER>.github.io/<REPO>/
对于自定义域名，请在仓库设置 > Pages > 自定义域名中配置
未来推送到 main 分支将通过工作流自动部署

🇺🇸English

GitHub Pages Deployment

Command

/github-page or github-page

Navigate

Deployment

Keywords

Description

Deploy any project to GitHub Pages with zero manual configuration. Automatically detects your project type, generates the correct GitHub Actions workflow, enables GitHub Pages and Actions on the repo via API, and gives you a live URL.

Execution

This skill runs using Claude Code with subscription plan. Do NOT use pay-as-you-go API keys. All AI operations should be executed through the Claude Code CLI environment with an active subscription.

Response

I'll help you deploy to GitHub Pages!

The workflow includes:

Step	Description
Pre-flight	Verify `gh` CLI, git remote, and repo access
Detect Project	Auto-detect project type and build config
Generate Workflow	Create `.github/workflows/deploy-pages.yml`
Push & Enable	Push workflow, enable GitHub Pages + Actions via API
Verify	Confirm deployment and provide live URL

Instructions

When executing /github-page, follow this workflow:

Phase 1: Pre-flight Checks

1.1 Verify GitHub CLI

gh --version

If not installed, inform the user:

ERROR: GitHub CLI (gh) not found.
Install: https://cli.github.com/

1.2 Verify Authentication

gh auth status

If not authenticated:

ERROR: Not logged in to GitHub CLI.
Run: gh auth login

1.3 Verify Git Remote

git remote get-url origin

Extract OWNER and REPO from the remote URL:

# For HTTPS: https://github.com/OWNER/REPO.git
# For SSH: git@github.com:OWNER/REPO.git
REMOTE_URL=$(git remote get-url origin)
OWNER=$(echo "$REMOTE_URL" | sed -E 's#.*(github\.com)[:/]([^/]+)/([^/.]+)(\.git)?$#\2#')
REPO=$(echo "$REMOTE_URL" | sed -E 's#.*(github\.com)[:/]([^/]+)/([^/.]+)(\.git)?$#\3#')

If no remote exists:

ERROR: No GitHub remote found.
Add one with: git remote add origin https://github.com/USER/REPO.git

Phase 2: Detect Project Type

Analyze the project to determine build commands and output directory.

2.1 Detection Rules

Indicator	Project Type	Build Command	Output Dir
`vite.config.*`	Vite (React/Vue/Svelte)	`npm install && npm run build`	`./dist`
`next.config.*`	Next.js (static export)	`npm install && npm run build`	`./out`
`angular.json`

2.2 Framework-Specific Configuration

Vite projects — Ensure base is set in vite.config.*:

export default defineConfig({
  base: '/<REPO>/',
})

Inform the user if base is not set — the site will have broken asset paths without it.

Next.js projects — Ensure output: 'export' is in next.config.*:

const nextConfig = {
  output: 'export',
  basePath: '/<REPO>',
}

2.3 Node.js Version Detection

Check for .nvmrc, .node-version, or engines.node in package.json to set the correct Node.js version in the workflow. Default to 20 if not specified.

Phase 3: Generate GitHub Actions Workflow

Create .github/workflows/deploy-pages.yml:

3.1 Static HTML (No Build Step)

name: Deploy to GitHub Pages

on:
  push:
    branches: [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: Setup Pages
        uses: actions/configure-pages@v5

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v4
        with:
          path: '.'

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

3.2 Node.js Project (React/Vite/Next.js/Angular)

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

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

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '<NODE_VERSION>'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

      - name: Setup Pages
        uses: actions/configure-pages@v5

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v4
        with:
          path: '<OUTPUT_DIR>'

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Replace <NODE_VERSION> and <OUTPUT_DIR> with detected values from Phase 2.

3.3 Create the Workflow File

mkdir -p .github/workflows

Write the appropriate workflow YAML to .github/workflows/deploy-pages.yml.

Phase 4: Enable GitHub Pages & Actions (Auto-configure)

4.1 Commit and Push the Workflow

git add .github/workflows/deploy-pages.yml
git commit -m "$(cat <<'EOF'
ci: add GitHub Pages deployment workflow

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"
git push origin main

Important: Always add specific files. Never use git add . or git add -A.

4.2 Enable GitHub Pages via API

First, check if Pages is already enabled:

gh api "/repos/$OWNER/$REPO/pages" 2>/dev/null

If not enabled (404 response), create it:

gh api -X POST "/repos/$OWNER/$REPO/pages" -f build_type=workflow

If already enabled but using a different source, update it:

gh api -X PUT "/repos/$OWNER/$REPO/pages" -f build_type=workflow

4.3 Enable the Workflow

gh workflow enable deploy-pages.yml

4.4 Trigger Initial Deployment (if push didn't trigger it)

gh workflow run deploy-pages.yml

Phase 5: Verify & Report

5.1 Check Workflow Run

Wait a few seconds, then check:

gh run list --workflow=deploy-pages.yml --limit 1

5.2 Print Results

=== GitHub Pages Deployment ===

Workflow: .github/workflows/deploy-pages.yml (created)
GitHub Pages: ENABLED (source: GitHub Actions)
GitHub Actions: ENABLED

Deployment URL: https://<OWNER>.github.io/<REPO>/
Workflow runs: https://github.com/<OWNER>/<REPO>/actions

Status: Deploying... (check Actions tab for progress)

5.3 If Errors Occur

Pages API returns 409 (conflict):

Pages may already be configured with a branch source
Update with PUT instead of POST

Workflow not triggering:

Ensure the branch name matches (main vs master)

Check if Actions are enabled at the repo level:

gh api -X PUT "/repos/$OWNER/$REPO/actions/permissions" -f enabled=true

Build fails:

Check the workflow run logs:
```
gh run view --log
```
Common issues: missing base config for Vite, missing output: 'export' for Next.js

Capabilities

Auto-detect project type (static HTML, React, Vite, Next.js, Angular, MkDocs)
Generate correct GitHub Actions workflow for the project
Enable GitHub Pages with Actions source via API
Enable GitHub Actions on the repo automatically
Trigger initial deployment
Support for custom build commands and output directories
Node.js version detection from project config

Next Steps

After running /github-page:

Check the Actions tab: https://github.com/<OWNER>/<REPO>/actions
Wait for the first deployment to complete (usually 1-2 minutes)
Visit your live site: https://<OWNER>.github.io/<REPO>/
For custom domains, configure in repo Settings > Pages > Custom domain
Future pushes to main will auto-deploy via the workflow

Weekly Installs

Repository

alfredang/skills

GitHub Stars

First Seen

Jan 1, 1970

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

147,400 周安装