Deploy github pages domain

部署 GitHub Pages 自定义域名

把 GitHub Pages、Cloudflare DNS、仓库信息和部署后验证整合成一个受保护的工作流。优先使用附带脚本执行确定性的 API 修改。

必要输入

修改外部状态前，先确定以下信息：

• GitHub 仓库，格式为 OWNER/REPO；在仓库目录中工作时，使用 gh repo view --json nameWithOwner 自动获取。
• 完整自定义域名，例如 resume.xiaojunfan.top。
• Cloudflare Zone，例如 xiaojunfan.top。脚本默认取域名最后两段，但遇到 example.co.uk 一类域名时，必须显式传入 --zone。
• GitHub Pages 目标地址。默认使用 OWNER.github.io；如果 Pages 所属账号和仓库 Owner 不同，使用 --target 覆盖。
• 可选的仓库描述和 Topics。

只询问无法安全获取的信息。不要让用户在对话中粘贴密钥。

安全规则

• 对解释和检查类请求只执行只读操作，先在不带 --apply 的情况下运行。
• 用户明确说“配置、部署、修改、修复”时，可以执行对应范围内的 GitHub 和 Cloudflare 修改，但应用前仍需展示获取到的当前状态。
• 不要输出 CLOUDFLARE_API_TOKEN、GitHub Token 或 Authorization Header。
• 在 macOS 上优先把 Cloudflare Token 保存到系统钥匙串。公开仓库中只保留固定的服务名 deploy-github-pages-domain.cloudflare，不要保存凭据本身。
• 要求使用仅限目标 Zone、具备 Zone Read 和 DNS Edit 权限的 Cloudflare API Token；不要使用 Global API Key。
• 创建精确的 CNAME 记录，不要创建通配符 DNS 记录。
• GitHub Pages 默认设置 proxied=false。只有用户明确要求 Cloudflare Proxy 并接受额外的 TLS 和排障复杂度时，才使用 --proxied。
• 如果同名位置存在冲突的 A、AAAA、NS 或其他类型记录，不要删除或改变其类型；停止并报告冲突。
• 不要自动创建或更改 GitHub Pages 发布模式。如果 Pages 尚未启用，先检查项目，再询问使用自定义 Actions Workflow 还是分支发布。
• 从未被占用的主机名开始配置时，先设置仓库的 Pages 自定义域名，再创建 DNS。
• 建议在 GitHub 账号的 Pages 设置中验证一次根域名，并永久保留对应的 TXT 验证记录。

操作流程

1. 检查前置条件

执行：

gh auth status
python3 scripts/setup_cloudflare_token.py --status
python3 scripts/configure_pages_domain.py --help

不要输出 Token。确认当前 GitHub 账号拥有仓库管理权限，并且 GitHub Pages 已启用。

2. 长期保存 Cloudflare Token

首次使用时运行：

python3 scripts/setup_cloudflare_token.py

脚本会在终端中隐藏输入、调用 Cloudflare 官方接口验证 Token，然后保存到当前 macOS 用户的登录钥匙串。以后部署脚本会按以下顺序查找凭据：

1. 当前进程的 CLOUDFLARE_API_TOKEN 环境变量，用于临时覆盖。
2. macOS 钥匙串项目 deploy-github-pages-domain.cloudflare，用于长期使用。

检查状态或删除旧 Token：

python3 scripts/setup_cloudflare_token.py --status
python3 scripts/setup_cloudflare_token.py --delete

3. 生成预演计划

在本 Skill 目录中运行：

python3 scripts/configure_pages_domain.py \
  --repo OWNER/REPO \
  --domain SUBDOMAIN.EXAMPLE.COM \
  --zone EXAMPLE.COM \
  --description "仓库描述"

不添加 --apply 时，脚本只读取 GitHub 和 Cloudflare 当前状态并打印计划，不会执行修改。只有在没有凭据或无法联网、仅需验证参数时才使用 --offline-plan；该模式不会检查线上状态。

4. 应用限定范围内的修改

检查计划后，添加 --apply：

python3 scripts/configure_pages_domain.py \
  --repo OWNER/REPO \
  --domain SUBDOMAIN.EXAMPLE.COM \
  --zone EXAMPLE.COM \
  --description "仓库描述" \
  --topic portfolio \
  --topic github-pages \
  --apply

确保脚本依次完成：

1. 通过 gh api 更新 GitHub Pages 的 cname。
2. 幂等创建或更新精确的 Cloudflare CNAME。
3. 把仓库 About 主页设置为 https://CUSTOM_DOMAIN。
4. 更新可选的仓库描述和 Topics。
5. 重新读取两个服务，报告实际状态。

5. 处理仓库文件

• 使用自定义 GitHub Actions Pages Workflow 时，不要创建 CNAME 文件；GitHub 会忽略它。
• 使用分支发布时，确保发布源根目录中存在名称严格为 CNAME 的文件，内容只能是自定义域名并以换行结尾。
• Vite 或类似网站使用自定义域名时，除非项目有意部署在路径下，否则确保生产环境的 Base Path 为 /。
• 只有用户明确要求，或现有 README.md 包含旧地址/默认地址时，才更新 README。保留原有结构，只替换相关 URL 或部署说明。
• 不要提交或推送无关修改。如果用户要求完整部署，提交限定范围内的文件修改，并验证推送后的实际结果。

6. 验证实际效果

重新运行不带 --apply 的脚本，或执行：

gh api repos/OWNER/REPO/pages
gh api repos/OWNER/REPO/pages/health
dig +short CNAME SUBDOMAIN.EXAMPLE.COM

Pages 健康检查接口第一次可能返回空的 202 响应。稍后重试，不要过早宣称成功或失败。

GitHub 批准证书后，使用以下命令启用 HTTPS：

python3 scripts/configure_pages_domain.py \
  --repo OWNER/REPO \
  --domain SUBDOMAIN.EXAMPLE.COM \
  --zone EXAMPLE.COM \
  --enforce-https \
  --apply

证书不可用时，不要强制开启 HTTPS。报告待处理状态，并保持现有配置不变。

故障处理

• GitHub 返回 404 时，结合 gh repo view 和 Pages 接口，区分“仓库不存在/没有权限”和“Pages 未启用”。
• Cloudflare 认证或权限失败时，停止操作并说明最低所需 Token 权限。
• DNS 冲突时，报告每条现有记录的类型和值，不要删除记录。
• 证书延迟时，说明 DNS 已配置、HTTPS 仍在签发。
• GitHub Pages 健康检查返回 202 时，说明“检查已开始/仍在等待”，只在用户要求的监控时间内重试。

需要查询接口细节、Pages 发布模式差异或排障规则时，阅读 references/api-notes.md。