GitHub Deploy Doctor

GitHub Deploy Doctor (gdh) is a deployment diagnostic tool for GitHub Pages, Hexo, and static websites.

它面向新手，把“本地项目到 GitHub / GitHub Pages 成功部署”中最常见的问题做成一站式体检报告：环境、网络、Git、GitHub 认证、Hexo 配置、GitHub Actions Pages workflow。

What It Checks

• Git / Node.js / npm / Hexo / GitHub CLI
• GitHub DNS、github.com:443、github.com:22
• raw.githubusercontent.com 和 objects.githubusercontent.com
• 当前目录是否是 Git 仓库
• remote origin 是否存在、格式是否合理、远程仓库是否可访问
• 当前分支、upstream、未提交改动
• gh auth status 登录状态
• ssh -T [email protected] SSH Key 认证状态
• Hexo _config.yml、deploy.type、deploy.repo、deploy.branch
• hexo-deployer-git 是否安装
• GitHub Pages Actions workflow 是否存在、是否包含构建、上传 artifact 和部署步骤

Usage

This package is not published to npm yet. Use the local commands while developing:

npm run doctor

or:

node ./bin/gdh.js doctor

If you want the short gdh command locally:

npm link
gdh doctor

After the package is published to npm, this will work:

npx github-deploy-doctor doctor

常用命令：

gdh doctor
gdh doctor --json
gdh network
gdh auth
gdh init-actions --hexo
gdh init-actions --hexo --branch main --dry-run
gdh fix --dry-run
gdh fix --actions --hexo --repo [email protected]:user/user.github.io.git --yes
gdh deploy --dry-run
gdh report --json

Example Output

GitHub Deploy Doctor

[环境检查]
✔ Git 已安装: git version 2.45.0
✔ Node.js 已安装: v20.11.1
✔ npm 已安装: 10.2.4
▲ GitHub CLI 未安装
  建议：可选安装 gh，用于检查 GitHub 登录状态和 Pages 配置。

[网络检查]
✖ GitHub HTTPS 443 端口连接失败
  建议：检查代理、DNS、网络防火墙，或尝试设置 Git HTTPS 代理。

[Git 检查]
✔ 当前目录是 Git 仓库
✔ remote origin 已配置: [email protected]:user/blog.git (SSH)
▲ 当前分支 main 未设置 upstream
  修复命令：git push -u origin main

[Hexo 检查]
✔ 检测到 Hexo 项目
✖ deploy.repo 缺失
  修复命令：gdh fix --hexo --repo [email protected]:<user>/<repo>.git --branch gh-pages --yes

GitHub Actions Mode

gdh init-actions --hexo creates .github/workflows/pages.yml for Hexo:

• checkout source
• setup Node.js
• run npm ci when package-lock.json exists, otherwise run npm install
• run npx hexo generate
• upload public/ with actions/upload-pages-artifact
• deploy with actions/deploy-pages

The generated workflow follows GitHub Pages custom workflow guidance: a build job uploads a Pages artifact and a deploy job grants pages: write and id-token: write.

Reference: GitHub Docs - Using custom workflows with GitHub Pages

Hexo One-Command Deploy Mode

Hexo deploy mode uses _config.yml:

deploy:
  type: git
  repo: [email protected]:username/username.github.io.git
  branch: gh-pages

Then deploy with:

npx hexo clean
npx hexo generate
npx hexo deploy

Warning: hexo-deployer-git may force push the deploy branch. Do not manually edit files directly on gh-pages if Hexo owns that branch.

Safety Rules

• gdh doctor only diagnoses.
• gdh fix previews by default.
• gdh fix --yes is required before writing files.
• Existing workflow or deploy config is not overwritten unless --force is provided.
• Dangerous operations such as git push --force, branch deletion, or .deploy_git deletion are not performed by this MVP.

MVP Scope

This first version is intentionally zero-dependency ESM JavaScript so it can run before package installation problems are solved. A later TypeScript package can replace the built-in argument parser, YAML-lite reader, and process runner with commander, yaml, and execa.