prcheckloop

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PRCheckloop

Get a GitHub PR to a fully green check state, or exit with a concrete blocker.

使GitHub PR达到完全检查通过的状态，或在遇到明确阻塞问题时退出。

Scope

适用范围

GitHub PRs only. If the repo is GitLab, stop and use
```
check-pr
```
.
Focus on checks for the latest PR head SHA, not old commits.
Focus on CI/status checks, not review comments or PR template cleanup.
If the user also wants review-comment cleanup, pair this with
```
check-pr
```
.

仅支持GitHub PR。如果仓库托管在GitLab，请停止使用并改用
```
check-pr
```
。
仅关注最新PR头部SHA的检查，忽略旧提交的检查。
专注于CI/状态检查，不处理评审评论或PR模板清理。
如果用户同时需要清理评审评论，请将此工具与
```
check-pr
```
配合使用。

Inputs

输入项

PR number (optional): If not provided, detect the PR for the current branch.
Max iterations: default
```
5
```
.

PR编号（可选）：如果未提供，将自动检测当前分支对应的PR。
最大迭代次数：默认值为
```
5
```
。

Workflow

工作流程

1. Identify the PR

1. 识别PR

If no PR number is provided, detect it from the current branch:

bash

gh pr view --json number,headRefName,headRefOid,url,isDraft

If needed, switch to the PR branch before making changes.

Stop early if:

```
gh
```
is not authenticated
there is no PR for the branch
the repo is not hosted on GitHub

如果未提供PR编号，将从当前分支自动检测：

bash

gh pr view --json number,headRefName,headRefOid,url,isDraft

如有需要，在修改前切换到PR对应的分支。

如果出现以下情况，将提前终止流程：

```
gh
```
未完成身份验证
当前分支没有对应的PR
仓库未托管在GitHub

2. Track the latest head SHA

2. 跟踪最新头部SHA

Always work against the current PR head SHA:

bash

PR_JSON=$(gh pr view "$PR_NUMBER" --json number,headRefName,headRefOid,url)
HEAD_SHA=$(echo "$PR_JSON" | jq -r .headRefOid)
PR_URL=$(echo "$PR_JSON" | jq -r .url)

Ignore failing checks from older SHAs. After every push, refresh

HEAD_SHA

and restart the inspection loop.

始终基于当前PR的头部SHA开展工作：

bash

PR_JSON=$(gh pr view "$PR_NUMBER" --json number,headRefName,headRefOid,url)
HEAD_SHA=$(echo "$PR_JSON" | jq -r .headRefOid)
PR_URL=$(echo "$PR_JSON" | jq -r .url)

忽略旧SHA的失败检查。每次推送后，刷新

HEAD_SHA

并重启检查循环。

3. Inventory checks for that SHA

3. 统计该SHA的所有检查项

Fetch both GitHub check runs and legacy commit status contexts:

bash

gh api "repos/{owner}/{repo}/commits/$HEAD_SHA/check-runs?per_page=100"
gh api "repos/{owner}/{repo}/commits/$HEAD_SHA/status"

For a compact PR-level view, this GraphQL payload is useful:

bash

gh api graphql -f query='
query($owner:String!, $repo:String!, $pr:Int!) {
  repository(owner:$owner, name:$repo) {
    pullRequest(number:$pr) {
      headRefOid
      url
      statusCheckRollup {
        contexts(first:100) {
          nodes {
            __typename
            ... on CheckRun { name status conclusion detailsUrl workflowName }
            ... on StatusContext { context state targetUrl description }
          }
        }
      }
    }
  }
}' -F owner=OWNER -F repo=REPO -F pr="$PR_NUMBER"

获取GitHub检查运行记录和传统提交状态上下文：

bash

gh api "repos/{owner}/{repo}/commits/$HEAD_SHA/check-runs?per_page=100"
gh api "repos/{owner}/{repo}/commits/$HEAD_SHA/status"

如需PR级别的紧凑视图，以下GraphQL请求非常实用：

bash

gh api graphql -f query='
query($owner:String!, $repo:String!, $pr:Int!) {
  repository(owner:$owner, name:$repo) {
    pullRequest(number:$pr) {
      headRefOid
      url
      statusCheckRollup {
        contexts(first:100) {
          nodes {
            __typename
            ... on CheckRun { name status conclusion detailsUrl workflowName }
            ... on StatusContext { context state targetUrl description }
          }
        }
      }
    }
  }
}' -F owner=OWNER -F repo=REPO -F pr="$PR_NUMBER"

4. Wait for checks to actually run

4. 等待检查实际运行

After a new push, checks can take a moment to appear. Poll every 15-30 seconds until one of these is true:

checks have appeared and every item is in a terminal state
checks have appeared and at least one failed
no checks appear after a reasonable wait, usually 2 minutes

Treat these as terminal success states:

check runs:
```
SUCCESS
```
,
```
NEUTRAL
```
,
```
SKIPPED
```
status contexts:
```
SUCCESS
```

Treat these as pending:

check runs:

QUEUED

PENDING

WAITING

REQUESTED

IN_PROGRESS

status contexts:
```
PENDING
```

Treat these as failures:

check runs:

FAILURE

TIMED_OUT

CANCELLED

ACTION_REQUIRED

STARTUP_FAILURE

STALE

status contexts:
```
FAILURE
```
,
```
ERROR
```

If no checks appear for the latest SHA, inspect

.github/workflows/

, workflow path filters, and branch protection expectations. If the missing check cannot be caused or fixed from the repo, escalate.

新推送后，检查可能需要一段时间才会启动。每15-30秒轮询一次，直到出现以下情况之一：

检查已启动且所有项均处于终态
检查已启动且至少有一项失败
经过合理等待（通常为2分钟）后仍未出现检查

以下状态视为终态成功：

检查运行：
```
SUCCESS
```
、
```
NEUTRAL
```
、
```
SKIPPED
```
状态上下文：
```
SUCCESS
```

以下状态视为待处理：

检查运行：

QUEUED

、

PENDING

、

WAITING

、

REQUESTED

、

IN_PROGRESS

状态上下文：
```
PENDING
```

以下状态视为失败：

检查运行：

FAILURE

、

TIMED_OUT

、

CANCELLED

、

ACTION_REQUIRED

、

STARTUP_FAILURE

、

STALE

状态上下文：
```
FAILURE
```
、
```
ERROR
```

如果最新SHA未出现任何检查，请检查

.github/workflows/

、工作流路径过滤器和分支保护规则。如果缺失的检查无法通过仓库内操作触发或修复，则上报阻塞问题。

5. Investigate failing checks

5. 排查失败的检查

For GitHub Actions failures, inspect runs and failed logs for the current SHA:

bash

gh run list --commit "$HEAD_SHA" --json databaseId,workflowName,status,conclusion,url,headSha
gh run view <RUN_ID> --json databaseId,name,workflowName,status,conclusion,jobs,url,headSha
gh run view <RUN_ID> --log-failed

For each failing check, classify it:

Failure type	Action
Code/test regression	Reproduce locally, fix, and verify
Lint/type/build mismatch	Run the matching local command from the workflow and fix it
Flake or transient infra issue	Rerun once if evidence supports flakiness
External service/status app failure	Escalate with the details URL and owner guess
Missing secret/permission/branch protection issue	Escalate immediately

Only rerun a failed job once without code changes. Do not loop on reruns.

对于GitHub Actions失败，检查当前SHA的运行记录和失败日志：

bash

gh run list --commit "$HEAD_SHA" --json databaseId,workflowName,status,conclusion,url,headSha
gh run view <RUN_ID> --json databaseId,name,workflowName,status,conclusion,jobs,url,headSha
gh run view <RUN_ID> --log-failed

对每个失败的检查进行分类：

失败类型	操作
代码/测试回归	在本地复现问题，修复并验证
代码规范/类型检查/构建不匹配	运行工作流中对应的本地命令并修复问题
不稳定或临时基础设施问题	如果有证据表明是不稳定问题，重新运行一次
外部服务/状态应用故障	附带详情URL和推测的负责人信息上报阻塞
缺失密钥/权限/分支保护问题	立即上报阻塞

未修改代码的情况下，仅重新运行失败任务一次。不要在重新运行环节循环。

6. Fix actionable failures

6. 修复可处理的失败

If the failure is actionable from the checked-out code:

Read the workflow or failing command to identify the real gate.
Reproduce locally where reasonable.
Make the smallest correct fix.
Run focused verification first, then broader verification if needed.
Commit in a logical commit.
Push before re-checking the PR.

Do not stop at a local fix. The loop is only complete when the remote PR checks for the new head SHA are green.

如果失败可通过已检出的代码修复：

查看工作流或失败命令，确定实际的检查要求。
尽可能在本地复现问题。
做出最小且正确的修复。
先进行针对性验证，必要时再进行全面验证。
按逻辑提交更改。
推送更改后重新检查PR。

不要停留在本地修复阶段。只有当新头部SHA的远程PR检查全部通过时，循环才会结束。

7. Push and repeat

7. 推送并重复流程

After each fix:

bash

git push
sleep 5

Then refresh the PR metadata, get the new

HEAD_SHA

, and restart from Step 3.

Exit the loop only when:

all checks for the latest head SHA are green, or
a blocker remains after reasonable repair effort, or
the max iteration count is reached

每次修复后执行：

bash

git push
sleep 5

然后刷新PR元数据，获取新的

HEAD_SHA

，并从步骤3重新开始。

仅在以下情况退出循环：

最新头部SHA的所有检查均通过
经过合理修复尝试后仍存在阻塞问题
达到最大迭代次数

8. Escalate blockers precisely

8. 精准上报阻塞问题

If you cannot get the PR green, report:

PR URL
latest head SHA
exact failing or missing check names
details URLs
what you already tried
why it is blocked
who should likely unblock it
the next concrete action

Good blocker examples:

external status app outage
missing GitHub secret or permission
required check name mismatch in branch protection
persistent flake after one rerun
failure needs credentials or infrastructure access you do not have

如果无法使PR检查全部通过，请报告以下信息：

PR URL
最新头部SHA
确切的失败或缺失检查名称
详情URL
已尝试的操作
阻塞原因
可能负责解决阻塞的人员
下一步具体操作

优秀的阻塞问题示例：

外部状态应用故障
缺失GitHub密钥或权限
分支保护规则中要求的检查名称不匹配
重新运行一次后仍存在的持续不稳定问题
失败需要你没有的凭据或基础设施访问权限

Output

输出

When the skill completes, report:

PR URL and branch
final head SHA
green/pending/failing check summary
fixes made and verification run
whether changes were pushed
blocker summary if not fully green

工具完成后，将报告以下信息：

PR URL和分支
最终头部SHA
通过/待处理/失败检查的汇总
已完成的修复和验证操作
是否推送了更改
若未完全通过，阻塞问题的汇总

Notes

说明

This skill is intentionally narrower than
```
check-pr
```
: it is a repair loop for PR checks.
This skill complements
```
greploop
```
: Greptile can be perfect while CI is still red.

本工具的范围特意比
```
check-pr
```
更窄：它是针对PR检查的修复循环工具。
本工具与
```
greploop
```
互补：Greptile可能在CI仍未通过时就已完成工作。