SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场setup-repo-guards

setup-repo-guards

部署与运维

查看项目

更新于 10-15 15:12

技能介绍

用途

setup-repo-guards 用于向目标仓库导入 Fandhe-AI 组织标准的 CI 防护套件。导入内容共四项，按 Step 1 → 4 的顺序推进，每个 Step 需经 PR → CI 全部通过 → 审查线程 resolve → squash merge 确认后，再进入下一步。

采用该顺序的原因：存在「必需检查中要放入的聚合作业必须先存在」「AGENTS.md 因按 PR 的 base 提交引用，需在合并后的下一个 PR 起才生效」这样的依赖关系，按此顺序可自然满足。

主要能力（四个 Step）

Step 1：导入 ai-review（未导入时）

添加 .github/workflows/ai-review.yml 作为 wrapper，以可变标签 @latest 引用 Fandhe-AI/actions 的 reusable workflow ai-review.yml（不使用 commit SHA 固定或 @main）。旧 codex-review.yml 已从 Fandhe-AI/actions 删除，新导入不使用；若残留旧文件，需按 ai-review/README.md「从 codex-review 迁移」的步骤替换。wrapper 通过复制单 provider 模板生成（默认 provider: codex，作业 ID codex）。

runner 方针：CI 作业 public 用 ubuntu 托管，private 用 self-hosted；仅 ai-review 的 review 作业为专用 runner 例外。preflight / post_feedback 默认按可见性自动切换，无需显式指定。凭据 CODEX_HOME_DIR 作为 org 级 Actions variable 设置，不在仓库设置。若存在 update-external 的每日同步 PR，可指定 skip-branch-prefixes；有第三方 write 协作者时不要指定。collaborators-only 保持默认 true。凭据不可用期间 review 作业会 skipped，workflow 整体看似成功，导入 PR 必须按作业单位确认 review 已执行。

Step 2：添加 AGENTS.md（AI 审查观点集）

ai-review 读取 PR base 提交的 AGENTS.md 作为仓库固有审查基准。在仓库根目录用日语新建（已有则在不弱化基准的前提下补充缺失观点）。必须将三个观点落到目标仓库固有具体项：安全观点、架构与设计一致性观点、复用与资产化观点。另需从 CLAUDE.md / .claude/rules/ / 设计文档提取仓库固有观点，标注严重度 P0（阻止合并）/ P1（强烈推荐）/ P2（建议），且 P1 定义不得与 CI 门禁实际行为矛盾。已有自定义 prompt 时避免双重管理：观点以 AGENTS.md 为准，enforcement 以 review.md 为准。新基准自合并后的下一个 PR 起生效。

Step 3：整备 CI 必需检查的聚合作业

对拥有多个作业的 workflow 添加聚合作业（如 ci-complete）：将所有作业列入 needs:，加 if: always()，用 jq 判定 toJSON(needs)。严守 fail-closed：skipped 的容许仅限「带 if: 的条件作业」显式列表，其他作业只接受 success。有 change detection 门禁时，仅在门禁输出表明「skip 正确」的情况下接受 skipped。聚合作业加 permissions: {}，并写明「添加作业时需加入 needs」的注释。使用 reusable workflow 时，将引用 bump 到含聚合作业的 SHA 可归并为一条检查。YAML 的 name: 含 # 或「: 」时必须加引号。

Step 4：branch protection / 仓库设置（仅 GitHub API，无需提交）

合并设置：仅 squash、合并后自动删除分支、允许 auto-merge、squash 标题 = PR_TITLE / 正文 = PR_BODY。ruleset main-protection（target: branch、~DEFAULT_BRANCH、enforcement: active、bypass_actors 空）：禁止 deletion / non_fast_forward；pull_request 的 required_approving_review_count 为 0、required_review_thread_resolution 为 true、allowed_merge_methods 为 ["squash"]；required_status_checks 的 strict 必须为 false。必需集合随是否使用 autoMerge 而变。使用 autoMerge 时需为每个条目绑定发行方 App 的 integration_id，PUT 更新后必须执行三轴扫描。

必需检查选定的注意点：只选最近 PR 的 check runs 中「始终报告」的检查；workflow 级 paths 过滤导致可能不执行的检查不要纳入。不使用 autoMerge 时，Cursor Bugbot 等外部应用不设为必需；使用 autoMerge: true 时，需将 PR HEAD 报告的全部 context 列为必需并绑定 App ID。检查名变更的 PR 需在合并前用 PUT 将 ruleset 替换为新检查名。

附加防护：secret scanning + push protection / Dependabot alerts + automated security fixes /（public 时）private vulnerability reporting / 有标签运用时加 tag ruleset / GITHUB_TOKEN 默认权限 read 化 / Actions 的 PR 创建与批准许可（无自动 PR 运用时设为 false）/（private 时）禁止 forking / 禁用未使用的 wiki、projects。遇到套餐限制（403/422）的项目记录为「需要用户操作」并继续其他项。

使用方式

setup-repo-guards Fandhe-AI/my-repo public
setup-repo-guards Fandhe-AI/repo-a public Fandhe-AI/repo-b private

第 1 参数：目标仓库名（owner/repo）；第 2 参数：visibility（public / private），用于 runner 方针分支。批量应用时列举仓库与 visibility 的组合，在各仓库的会话（或并行 agent）中依次处理。

前提条件

  • 已安装 gh CLI，并以目标仓库 admin 权限认证（用 command -v gh && gh auth status 确认）
  • 已安装 jq（用 command -v jq 确认）
  • 对 Fandhe-AI/actions（reusable workflow 提供方）有引用权限
  • 已 clone 目标仓库，可读取 CLAUDE.md 与既有 workflow

验证

各 Step 完成后按以下方式确认：Step 1 用 grep 确认 wrapper 存在与 @latest 引用、确认无旧 codex-review.yml，并用 gh run view --json jobs 按作业单位确认 review 已执行；Step 2 用 grep 确认 AGENTS.md 存在及 P0/P1/P2 定义；Step 3 用 gh pr checks 确认聚合作业被报告；Step 4 用 gh api 确认 ruleset 与合并设置，并执行三轴扫描（strict / bypass_actors / integration_id 残留）与 classic branch protection 的另行扫描。最终确认：导入后跑一个小 PR，观察 ai-review 执行、必需检查报告、仅允许 squash merge、必须 resolve 线程是否实际生效。

适用场景

需要为 Fandhe-AI 组织下的仓库统一导入 CI 防护、AI 自动审查、必需检查聚合与分支保护规则时使用；支持单仓库与多仓库批量应用。

限制与注意事项

  • 该技能必须进行跨网络的 GitHub 操作（ruleset 的 PUT、workflow 的分发），相关命令需按命令单位禁用 sandbox 执行；无法解除网络阻断的环境不能执行。
  • 提交使用日语 Conventional Commits 格式，遵循目标仓库的提交规约与 footer 运用，不使用 --no-verify。
  • 若 AI 审查的指摘正当，应以修正回应，不得通过弱化测试、门禁或跳过敷衍；回复处理内容并 resolve 线程后再合并。
  • 范围外的发现应建议用户建 Issue，不要擅自开票。
  • 常见失败包括：聚合作业 skipped 全容许被指为 fail-open、检查名变更 PR 因 ruleset 旧名而 BLOCKED、未加引号的 name: 导致 API 报告名不稳定、paths 过滤检查设为必需导致永久阻塞、AGENTS.md 的 P1 定义与门禁行为矛盾、GITHUB_TOKEN read 化破坏隐式 write 依赖、PUT 后 integration_id 绑定丢失导致自动合并静默停止、旧 ruleset / classic BP 漏扫、autoMerge 运用下外部应用或 post_feedback 未列为必需导致 G0 辞退、旧 codex-review.yml 残留导致 workflow 无法解析、preflight 未列为必需导致 actor 判定失败时 review skipped 仍满足必需检查、凭据未设置时 review skipped 却误判导入完成。
  • 关于收费、价格、平台支持范围等，资料未提供。