GitHub CLI / API Notes For babysit-pr

Primary commands used

PR metadata

• gh pr view --json number,url,state,mergedAt,closedAt,headRefName,headRefOid,headRepository,headRepositoryOwner

Used to resolve PR number, URL, branch, head SHA, and closed/merged state.

PR checks summary

• gh pr checks --json name,state,bucket,link,workflow,event,startedAt,completedAt

Used to compute pending/failed/passed counts and whether the current CI round is terminal.

Workflow runs for head SHA

• gh api repos/{owner}/{repo}/actions/runs -X GET -f head_sha=<sha> -f per_page=100

Used to discover failed workflow runs and rerunnable run IDs.

Failed log inspection

• gh run view <run-id> --json jobs,name,workflowName,conclusion,status,url,headSha
• gh api repos/{owner}/{repo}/actions/runs/{run_id}/jobs -X GET -f per_page=100
• gh api repos/{owner}/{repo}/actions/jobs/{job_id}/logs > /tmp/codex-gh-job-{job_id}-logs.zip
• gh run view <run-id> --log-failed

Used by Codex to classify branch-related vs flaky/unrelated failures. Prefer the direct job log endpoint as soon as a job has failed because gh run view --log-failed may not produce failed-job logs until the overall workflow run completes.

Retry failed jobs only

• gh run rerun <run-id> --failed

Reruns only failed jobs (and dependencies) for a workflow run.

Review-related endpoints

• Issue comments on PR:
  • gh api repos/{owner}/{repo}/issues/<pr_number>/comments?per_page=100
• Inline PR review comments:
  • gh api repos/{owner}/{repo}/pulls/<pr_number>/comments?per_page=100
• Review submissions:
  • gh api repos/{owner}/{repo}/pulls/<pr_number>/reviews?per_page=100

Use each inline comment's pull_request_review_id to find its parent review. Ignore parent reviews whose state is PENDING, along with their inline comments, until the review is submitted.

JSON fields consumed by the watcher

gh pr view

• number
• url
• state
• mergedAt
• closedAt
• headRefName
• headRefOid

gh pr checks

• bucket (pass, fail, pending, skipping)
• state
• name
• workflow
• link

Actions runs API (workflow_runs[])

• id
• name
• status
• conclusion
• html_url
• head_sha

Actions run jobs API (jobs[])

• id
• name
• status
• conclusion
• html_url