GitHub Actions 自动化分析

GitHub Guides 的推荐形态是“静态博客 + 本地分析 + 可选 Actions 自动化”。Pages 只发布已经审核的静态文件；Actions 负责在需要时生成研究草稿，不直接发布文章。

启用模板

模板位于仓库根目录：

.github/workflows/analyze-repository.yml.example

确认权限和组织策略后复制为：

.github/workflows/analyze-repository.yml

随后在 GitHub 的 Actions → Analyze GitHub repository → Run workflow 中输入 repository：完整 GitHub URL 或 owner/repo。工作流固定写入 articles/inbox/，不会接受指向 docs/guides 的输出路径。

Actions runner 每次从干净 checkout 开始，因此不会遇到本地草稿覆盖问题；本地重复分析仍受 --force 保护。

工作流会执行：

npm ci
  -> npm run repo:analyze
  -> npm run content:check
  -> upload artifact

artifact 默认保留 14 天，名称包含 workflow run id。下载后放回本地 articles/inbox/，再使用 github-guide-author Skill 补充源码分析。

权限与安全

模板只声明：

permissions:
  contents: read

公开仓库不需要额外 token。读取私有仓库时，github.token 只能访问当前 workflow 被授予的内容；组织策略或跨仓库访问不足时，任务应失败并报告证据缺口，不应绕过权限。不要把个人 token 放在 workflow 输入、文章、日志或 artifact 中。

仓库内容是不可信输入。分析命令只调用 GitHub REST API，不下载、安装依赖、运行脚本、启动容器或执行构建。工作流设置了 10 分钟超时，目录条目和 README 摘要也有上限。

人工发布门

Actions 成功不等于文章可以发布。必须在本地完成：

npm run content:check
# 使用 Skill 补充 manifest 指定的源码范围和证据
npm run content:promote -- --file articles/inbox/owner--repo/article.md --approve
npm run check
npm run pages:dev

确认以下事实后才允许提交和远端发布：source commit、许可证、命令前置条件、证据链接、验证状态、图片提示词文件和文章可见性。--approve 只提升到本地 docs/guides/，不代表 Git push、Cloudflare Pages 发布或 GitHub Pages 启用。

用 GitHub Copilot 修复 CI

仓库提供了一个默认不启用的模板：

.github/workflows/copilot-auto-fix.yml.example

模板监听现有 Validate 工作流。只有同一仓库分支的检查失败时才会运行；来自 fork 的失败不会获得写权限或 Copilot token。自动修复分支再次失败时也不会递归创建新任务。

执行流程如下：

Validate 失败
  -> 检出失败提交
  -> 下载失败步骤日志
  -> GitHub Copilot CLI 做最小修复
  -> git diff --check
  -> npm run check
  -> 创建人工审核 PR

当前远程仓库属于个人账户，不能依赖组织级 Copilot CLI 策略。启用前需要：

1. 为拥有有效 Copilot 订阅的用户创建细粒度 PAT，只授予账户级 Copilot Requests 权限。
2. 在仓库 Settings → Secrets and variables → Actions 中创建 COPILOT_CLI_TOKEN，值为上述 PAT。
3. 在 Settings → Actions → General → Workflow permissions 中允许 Actions 读写，并允许 Actions 创建 Pull Request。
4. 审阅模板中的触发条件和写权限，再复制为 .github/workflows/copilot-auto-fix.yml。

模板不再需要 OPENAI_API_KEY，也不使用 openai/codex-action。项目依赖通过 npm ci 安装；Copilot CLI 固定为 @github/copilot@1.0.82，升级前应检查官方变更记录并重新验证工作流。

如果仓库以后迁移到组织，并启用“Allow use of Copilot CLI billed to the organization”策略，可以改用内置 GITHUB_TOKEN：为工作流增加 copilot-requests: write，并让 COPILOT_GITHUB_TOKEN 读取 GitHub Actions 提供的 github.token。GitHub 官方对一般自动化更推荐 GitHub Agentic Workflows；当前模板保留直接 CLI 方式，是为了匹配“失败后修复并创建 PR”的现有流程。

直接在 Actions runner 中使用 Copilot CLI 仍会接触仓库内容和 Copilot token。模板没有使用允许全部工具的 --yolo，只开放读取、编辑、npm run check、npm test、git diff 和 git status；最终提交和 PR 由固定 Action 完成。不要扩大命令白名单，不要移除同仓库来源限制，不要在 pull_request_target 中检出外部 PR 代码，也不要让自动修复流程直接合并或推送到受保护分支。

为什么不自动创建 PR

仓库分析模板只生成 artifact，不自动创建 PR，因为研究草稿还需要人工核对证据。Copilot 自动修复模板是单独的可选流程，拥有 contents: write、pull-requests: write 和失败日志读取权限；该流程只处理 CI 根因，并且只能创建等待人工审核的修复 PR，不能 promote 内容、部署页面或自动合并。

故障处理

• Repository must be a GitHub URL or owner/repo：项目名称不唯一，请改用完整 URL 或 owner/repo。
• GitHub API 401/403：检查 token 权限、组织 SSO 和 API 速率限制；不要把 token 输出到日志。
• content:check 失败：下载完整 artifact，按错误修复草稿；不要跳过校验直接复制到 docs/guides/。
• README 或 Git tree 不完整：在文章中标为未知，并在 manifest 中缩小或调整源码分析范围。