github

连接方式选择

当 Agent 环境中有经过身份验证的 GitHub MCP 工具时，请优先使用。通过工具是否可用来判断，无需依赖特定的 MCP 服务名称。仅当 GitHub MCP 工具不可用，或明确需要原始 API 或 curl 访问时，才使用下方的令牌和直接 API 操作说明。

你可以使用环境变量 GITHUB_TOKEN 与 GitHub API 交互。

你可以使用 `curl` 和 `GITHUB_TOKEN` 与 GitHub API 交互。 操作时务必使用 GitHub API，而不是网页浏览器。 务必使用 `create_pr` 工具创建拉取请求。 如果用户要求你检查 GitHub Actions 状态，请先尝试使用 `gh` 操作工作流；如果失败，再使用基本 API 调用。 示例： - 使用 `gh run watch`（https://cli.github.com/manual/gh_run_watch）监控工作流运行 - 使用 `gh pr checks 200 --watch --interval 10` 等待检查完成。

下方多行 shell 代码片段对应的 Windows PowerShell 写法见 references/windows.md。

如果向 GitHub 推送时遇到身份验证问题（例如密码提示或权限错误），旧令牌可能已过期。这种情况下，请将远程 URL 更新为包含当前令牌的地址：git remote set-url origin https://${GITHUB_TOKEN}@github.com/username/repo.git

以下是推送说明，但仅在用户要求时执行：

• 切勿直接推送到 main 或 master 分支。
• Git 配置（用户名和邮箱）已预先设置。请勿修改。
• 你当前可能已位于以 openhands-workspace 开头的分支上。推送前请创建一个更合适的新分支。
• 如果尚未创建拉取请求，请使用 create_pr 工具创建。
• 创建自己的分支或拉取请求后，后续修改都应在该分支或拉取请求中继续。除非用户明确要求，否则不要另建分支或拉取请求。根据需要更新拉取请求的标题和描述，但不要更改分支名称。
• 除非用户另有要求，否则以 main 分支为目标分支。
• 创建或更新拉取请求后，请向用户发送一条简短消息，并附上拉取请求链接。
• 除非用户明确要求，否则不要将拉取请求标记为可供审查。
• 尽可能用最少的步骤完成上述操作。例如，可以通过运行以下 bash 命令一步推送更改：

git remote -v && git branch # to find the current org, repo and branch
git checkout -b create-widget && git add . && git commit -m "Create widget" && git push -u origin create-widget

合并拉取请求（异步合并 API）

重要： 只有在用户明确要求时才合并。

GitHub 于 2026 年 10 月发布了异步合并 API；这是目前以编程方式合并 PR 的推荐方式，也是唯一支持堆叠 PR 的合并 API。它还可以将 PR 加入合并队列。 优先使用此 API，而不要使用 PUT .../pulls/{n}/merge 或 GraphQL mergePullRequest mutation。 GitHub MCP 合并工具可能仍使用旧的同步端点；对于堆叠 PR 或合并队列，请使用以下调用。 文档：https://docs.github.com/en/rest/pulls/pulls#merge-a-pull-request-asynchronously

1. 请求合并（merge_action：default 会在分支有合并队列时使用该队列，否则直接合并；也可以选择 direct_merge / merge_queue）。merge_method、commit_title 和 commit_message 仅适用于直接合并：

gh api -X PUT repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>/merge-async -f merge_method=squash -f sha=<HEAD_SHA>

2. 返回 202 时会提供 details.uuid；每隔几秒轮询一次，直到 status 不再是 pending：

gh api repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>/merge-async/<UUID>

最终 status 为 merged（已合并）、enqueued（已加入合并队列，但尚未合并）或 failed（请查看 details.message）。 PUT 返回 200 表示 PR 已合并或已加入队列；返回 409 表示已有合并请求正在等待处理（会返回其 UUID）。

处理审查意见

• 在采取行动之前，先批判性地评估每条审查意见。并非所有反馈都值得采纳：
  • 它是否修复了实际 bug 或显著提升了清晰度？
  • 它是否符合项目的工程原则（简洁、易维护）？
  • 建议的改动是否与其带来的收益相称，还是会增加不必要的复杂性？
• 对于那些会增加篇幅却没有明显收益、针对假设的边缘情况过度设计，或与项目务实做法相悖的建议，可以礼貌地拒绝。
• 处理完（或决定不处理）内联审查意见后，将相应的审查讨论标记为已解决。
• 解决讨论之前，先留下回复评论，说明拒绝反馈的理由，或引用解决问题的具体提交（例如提交 SHA）。
• 最好等修复已推送或已记录明确决定后再解决讨论。
• 使用 GitHub GraphQL API 回复并解决审查讨论（见下文）。
• 修改 PR 后，确认标题和描述仍与内容相符。如果范围、功能或意图发生变化，请更新标题和描述。

通过 GraphQL 解决审查讨论

以编程方式解决现有审查讨论：

1. 获取讨论 ID（替换 <OWNER>、<REPO>、<PR_NUMBER>）：

gh api graphql -f query='
{
  repository(owner: "<OWNER>", name: "<REPO>") {
    pullRequest(number: <PR_NUMBER>) {
      reviewThreads(first: 20) {
        nodes {
          id
          isResolved
          comments(first: 1) {
            nodes { body }
          }
        }
      }
    }
  }
}'

2. 回复讨论，说明如何处理了反馈：

gh api graphql -f query='
mutation {
  addPullRequestReviewThreadReply(input: {
    pullRequestReviewThreadId: "<THREAD_ID>"
    body: "Fixed in <COMMIT_SHA>"
  }) {
    comment { id }
  }
}'

3. 解决讨论：

gh api graphql -f query='
mutation {
  resolveReviewThread(input: {threadId: "<THREAD_ID>"}) {
    thread { isResolved }
  }
}'

4. 获取失败的工作流运行 ID 并重新运行：

# Find the run ID from the failed check URL, or use:
gh run list --repo <OWNER>/<REPO> --branch <BRANCH> --limit 5

# Rerun failed jobs
gh run rerun <RUN_ID> --repo <OWNER>/<REPO> --failed