⚡

GitHubPR自动化加入操作技能 join

这个技能是一个自动化工具，专门用于通过GitHub CLI (`gh`) 管理Pull Requests，包括创建PR、更新分支、监控CI检查、实施最小修复，并准备PR以进行人工合并，但不执行实际合并。关键词：GitHub, PR自动化, CI/CD, DevOps, 代码审查, 自动化运维, 拉取请求管理。

DevOps 0 次安装 0 次浏览 更新于 3/8/2026

name: join description: “仅通过gh实现PR自动驾驶：创建/管理PR，保持分支最新，强制执行必要CI门禁，应用精准代码补丁，并在不合并的情况下发布合并就绪交接。当需要运行或监控PR自动化、修复失败的必需检查、保持本地/远程分支状态清洁，或为人工合并准备分支/PR清理时使用。”

加入操作

意图

运行一个连续的PR操作器，仅使用gh命令。保持PR创建、绿色且合并就绪，实施最小化修复。除非用户明确指示，否则不要批准或合并PR。

命令边界（硬规则）

  • 仅使用gh CLI命令（gh pr、gh run、gh api、gh repo）。
  • 不要运行git或任何非gh命令。
  • 如果必需操作无法仅用gh完成，应用auto:hold并留下阻塞性评论。

快速开始

  1. 确保gh auth status成功。
  2. 确保标签存在：auto:manage、auto:hold。
  3. 启动监控循环。

认证预检（必需）

  • 在任何PR路由或变更前运行这些检查：
    • gh auth status
    • gh repo view <owner>/<repo> --json nameWithOwner --jq .nameWithOwner
  • 如果任一检查失败：
    • 快速失败当前运行。
    • 在受影响的PR上应用auto:hold（或在无PR选中时在云循环中发出保持结果）。
    • 记录原因为auth_unavailable。

标签约定

  • auto:manage：选择加入自动化。
  • auto:hold：暂停自动化。

贡献者指南：

  • 添加auto:manage以选择加入。
  • 添加auto:hold以停止操作器。

PR创建策略（仅gh）

  • 对于每个通过gh api可发现的非默认分支（无开放PR），创建一个PR。
  • 如果存在仓库PR模板则使用；否则使用assets/pr-template.md。
  • 首选gh pr create --fill并应用auto:manage。
  • 默认设置为准备审查（无草稿，除非配置）。

操作模式

仅使用一种模式：

  • 仅gh远程模式：无本地检出假设和无本地工作区变更。

云加入操作器（$puff + seq -> join）

当作为云子代理循环运行加入操作时使用此模式：

  1. 使用$puff join-operator启动。
  2. 对于每个补丁工件，通过清单优先评分路由（包括通过gh pr view <num> --json files进行PR文件路径水合）。
  3. 如果映射/冲突处理不明确，首先运行$seq以恢复意图/上下文。
  4. 然后运行$join进行仅gh的PR操作和CI/交接行为。

启动配方：

  • "$PUFF_SCRIPT" join-operator --env <env-id-or-label> --repo <owner/repo> --patch-inbox <locator>
  • 金丝雀配方（一个有限循环）：
    • "$PUFF_SCRIPT" join-operator --env <env-id-or-label> --repo <owner/repo> --patch-inbox <locator> --canary

云认证备注：

  • 在云环境中，提供具有仓库范围权限的GH_TOKEN（或GITHUB_TOKEN）用于加入操作。

补丁清单约定

补丁生产者应发出符合以下验证的清单：

  • assets/cloud-join-manifest.schema.json

必需字段：

  • patch_id
  • producer
  • repo（owner/repo）
  • base_branch
  • changed_paths（非空）
  • intent_summary

可选路由提示：

  • target_pr_hint
  • issue_refs
  • confidence
  • patch_file

监控循环

顺序处理PR（每个PR在CI上阻塞）：

  1. 列出开放PR：gh pr list --state open --json number,title,headRefName,labels,isDraft。
  2. 对于每个PR：
    • 如果存在auto:hold则跳过。
    • 如果无auto:manage且非代理创建则跳过。
    • 如果是草稿，标记为就绪：gh pr ready <num>。
    • 保持分支最新：gh pr update-branch <num> --rebase（当可用时）。
    • 强制执行CI门禁（仅必需检查；见下文）。
    • 如果失败，运行精准修复循环。
    • 当绿色时，发布合并就绪交接状态。
    • 不要批准或合并。

CI门禁（仅必需检查）

  • 仅门控必需检查（gh pr checks --required）。可选检查不阻塞交接。
  • 检测“无门控”仓库/PR（无必需检查）：
    • 如果gh pr checks <num> --required --json name返回空列表，将CI视为绿色并继续交接。
  • 等待必需检查（阻塞）：
    • gh pr checks <num> --required --watch --fail-fast
    • 这会阻塞直到所有必需检查通过或第一个必需检查失败。
  • 停滞CI（10分钟无可见进展）：
    • 定义“进展”为必需检查快照（name、bucket、startedAt、completedAt）的任何变化。
    • 等待时，定期采样：gh pr checks <num> --required --json name,bucket,startedAt,completedAt。
    • 如果快照在10分钟内未变化，且并非所有检查为bucket=pass，应用auto:hold并留下总结性评论，附带停滞检查的链接。
    • 将bucket=pending、bucket=skipping和bucket=cancel视为“非绿色”（阻塞），直到解决；不要通过它们标记为交接就绪。
  • 深入GitHub Actions（当需要时）：
    • 识别检查链接：gh pr checks <num> --required --json name,bucket,link,workflow
    • 查找可能运行：gh run list --branch <headRefName> --limit 10
    • 实时监视运行：gh run watch <run-id> --compact --exit-status
    • 获取失败步骤日志：gh run view <run-id> --log-failed

精准修复循环（仅gh）

使用仅gh的最小变更使CI变绿：

  1. 从CI日志读取失败信息。
  2. 通过gh api在PR头分支上应用最小修复。
  3. 重新运行检查并重新评估。
  4. 限制尝试次数（默认3次）。在耗尽、权限问题或硬冲突时：
    • 留下总结性评论。
    • 作为最后手段请求变更。
    • 应用auto:hold。

交接（不合并）

  • 当必需检查绿色（或无必需检查）且无保持时：
    • 更新状态/评论以指示：准备人工审查/合并。
    • 保持PR开放。
  • 策略：
    • 永不运行gh pr merge（任何标志）。
    • 永不运行gh pr review --approve，除非用户明确指示。
  • 确认交接状态：
    • gh pr view <num> --json state,mergeStateStatus,reviewDecision

自适应轮询

  • 轮询间隔低于60秒，除非CI缓慢。
  • 使用最近CI持续时间退避（上限120秒）。
  • API错误时指数退避。

状态报告

  • 维护单个PR评论/检查运行，命名为Join Operator。
  • 原地更新（避免评论垃圾）。

仅gh阻塞评论模板

Join Operator：仅gh自动化阻塞

此PR需要超出仅gh边界的操作（例如，手动冲突解决或仅本地编辑路径）。
手动应用所需提交，然后移除`auto:hold`。

停滞CI评论模板

Join Operator：必需检查停滞

必需检查在10分钟内无进展。
调查链接的运行，解除CI阻塞，然后移除`auto:hold`。

配方（仅gh）

  • 默认分支：gh repo view --json defaultBranchRef --jq .defaultBranchRef.name
  • 分支发现：gh api repos/<owner>/<repo>/branches --paginate --jq '.[].name'
  • 创建：gh pr create --fill --head <branch> --label auto:manage
  • 开放PR：gh pr list --state open --json number,title,headRefName,labels,isDraft
  • 标记就绪：gh pr ready <num>
  • 更新分支：gh pr update-branch <num> --rebase
  • PR头OID：gh pr view <num> --json headRefOid --jq .headRefOid
  • 必需检查（总结）：gh pr checks <num> --required
  • 必需检查（监视）：gh pr checks <num> --required --watch --fail-fast
  • 必需检查（链接/JSON）：gh pr checks <num> --required --json name,bucket,link,workflow
  • Actions运行（按分支）：gh run list --branch <branch> --limit 10
  • Actions运行日志：gh run view <run-id> --log-failed
  • 请求变更：gh pr review <num> --request-changes --body "<原因>"
  • 交接状态：gh pr view <num> --json state,mergeStateStatus,reviewDecision
  • 交接备注（示例）：gh pr comment <num> --body "Join Operator：必需检查已绿色；准备人工合并。"

资产

  • assets/pr-template.md
  • assets/cloud-join-manifest.schema.json
  • assets/cloud-join-operator-prompt.md
  • scripts/build_cloud_join_prompt.py
  • scripts/manifest_router.py