Coverage for src/keel/github.py: 100%
307 statements
« prev ^ index » next coverage.py v7.16.2, created at 2026-10-20 19:17 +0000
« prev ^ index » next coverage.py v7.16.2, created at 2026-10-20 19:17 +0000
1"""Thin, fail-soft ``gh`` (GitHub CLI) wrappers (argv, no shell).
3Like :mod:`keel.git`, these build the exact ``gh`` command for each backbone
4operation and run it via the injectable ``_run`` seam. Command construction is
5unit-tested offline; live behaviour is opt-in.
6"""
8from __future__ import annotations
10import base64
11import json
12import random
13import re
14import time
15import urllib.parse
16from collections.abc import Sequence
18from .runner import CommandResult, run_argv
20_TRANSIENT_PATTERNS = (
21 "rate limit",
22 "secondary rate limit",
23 "too many requests",
24 "connection reset",
25 "connection refused",
26 "could not resolve host",
27 "network is unreachable",
28 "tls handshake",
29 "ssl error",
30 "timed out",
31 "timeout",
32 "500 internal server error",
33 "502 bad gateway",
34 "503 service unavailable",
35 "504 gateway timeout",
36 "http 429",
37 "http 500",
38 "http 502",
39 "http 503",
40 "http 504",
41)
44def is_transient_error(result: CommandResult) -> bool:
45 """Return whether ``result`` failed due to a transient network or rate limit error."""
46 if result.ok:
47 return False
48 if result.timed_out:
49 return True
50 combined = f"{result.stderr} {result.stdout}".lower()
51 for pattern in _TRANSIENT_PATTERNS:
52 if pattern in combined:
53 return True
54 return False
57def run_argv_retry(
58 argv: Sequence[str],
59 *,
60 cwd: str | None = None,
61 max_attempts: int = 3,
62 backoff_factor: float = 1.0,
63 jitter: bool = True,
64 _run=None,
65 _sleep=None,
66) -> CommandResult:
67 """Execute a ``gh`` command with jittered exponential backoff on transient errors.
69 Retries only transient network, 5xx server errors, or secondary rate limit errors.
70 Deterministic and dependency-free, with injectable ``_run`` and ``_sleep`` seams
71 for offline testing at 100% line + branch coverage.
72 """
73 sleep_fn = _sleep or time.sleep
74 attempt = 1
75 while True:
76 result = run_argv(argv, cwd=cwd, **_kw(_run))
77 if result.ok or attempt >= max_attempts or not is_transient_error(result):
78 return result
79 delay = backoff_factor * (2 ** (attempt - 1))
80 if jitter:
81 delay += random.uniform(0.0, 0.5) if _sleep is None else 0.1 # nosec B311
82 sleep_fn(delay)
83 attempt += 1
86def open_pr(
87 title: str, body: str, base: str, head: str, *, cwd: str | None = None, _run=None
88) -> CommandResult:
89 return run_argv(
90 ["gh", "pr", "create", "--title", title, "--body", body, "--base", base, "--head", head],
91 cwd=cwd,
92 **_kw(_run),
93 )
96def ci_conclusion(pr: int | str, *, cwd: str | None = None, _run=None) -> str | None:
97 """Return the PR's check-rollup state (e.g. SUCCESS/FAILURE/PENDING).
99 Three distinct answers, because collapsing them is what let a PR with **no
100 checks at all** read as clear to merge (issue #675):
102 * a conclusion string — checks reported, here is what they said
103 * ``""`` — ``gh`` answered and the rollup is **empty**: nothing ran for this
104 head. A fact about the *PR*.
105 * ``None`` — ``gh`` could not be asked. A fact about the *runner*.
107 Only the caller can weigh those, so this returns the empty string rather than
108 folding it into ``None``. :func:`keel.ship.ci_ran` reads the distinction.
110 ``statusCheckRollup`` retains every historical run of a check, not just the
111 latest — a check that failed once and was later rerun to green still carries
112 its old FAILURE conclusion in the raw list, and a freshly requeued rerun may
113 carry no timestamp at all yet. The ``--jq`` filter dedupes by check identity
114 (``context`` for legacy commit statuses, ``name`` for check runs — an empty
115 string is treated the same as absent, matching the Python-side dedupe used
116 by the merge gate) down to each check's most recent entry before collecting
117 conclusions. "Most recent" prefers an entry genuinely still in flight (no
118 ``conclusion`` yet *and* a recognized pending ``status``) over any
119 concluded one for the same check — a new run cannot be queued before the
120 previous one concluded — and otherwise compares ``completedAt``, falling
121 back to ``startedAt``. Requiring a recognized pending ``status`` (not
122 merely an absent ``conclusion``) means a malformed or unexpected payload
123 shape can never mask a genuine stale failure. This mirrors
124 :func:`keel.cli._rollup_recency`/``_PENDING_CHECK_STATES``, manually
125 verified against a real ``jq`` binary; jq output can't be exercised by
126 this module's offline unit tests (see the module docstring).
127 """
128 pending_states = '"EXPECTED","PENDING","QUEUED","REQUESTED","WAITING","IN_PROGRESS"'
129 jq = (
130 "[.statusCheckRollup[]] "
131 "| group_by("
132 '(.context | select(. != null and . != "")) '
133 '// (.name | select(. != null and . != "")) '
134 '// ""'
135 ") "
136 "| map(max_by(["
137 '((.conclusion == null or .conclusion == "") and '
138 '(((.status // .state) | if type == "string" then ascii_upcase else "" end) '
139 "| IN(" + pending_states + "))), "
140 '(.completedAt // .startedAt // "")'
141 "])) "
142 "| map("
143 'if (.conclusion != null and .conclusion != "") then .conclusion '
144 'elif (((.status // .state) | if type == "string" then ascii_upcase else "" end) '
145 "| IN(" + pending_states + ')) then "PENDING" '
146 'elif (.state != null and .state != "") then .state '
147 "else empty end"
148 ") "
149 '| unique | join(",")'
150 )
151 result = run_argv(
152 ["gh", "pr", "view", str(pr), "--json", "statusCheckRollup", "--jq", jq],
153 cwd=cwd,
154 **_kw(_run),
155 )
156 if not result.ok:
157 return None
158 return result.stdout.strip()
161def ci_check_names(pr: int | str, *, cwd: str | None = None, _run=None) -> list[str] | None:
162 """The distinct check identities reported for ``pr``, or ``None`` when ``gh`` failed.
164 Used for the **count** an operator sees, so "0 checks" is a visible fact rather
165 than something inferred from a blank word. Identity is ``context`` for legacy
166 commit statuses and ``name`` for check runs — the same identity
167 :func:`ci_conclusion` dedupes on, so the two views agree about what "one check"
168 is. ``[]`` means the rollup is genuinely empty; ``None`` means ``gh`` could not
169 be asked.
170 """
171 jq = (
172 "[.statusCheckRollup[] "
173 '| (.context | select(. != null and . != "")) '
174 '// (.name | select(. != null and . != "")) '
175 "// empty] "
176 "| unique | .[]"
177 )
178 return _rollup_strings(pr, jq, cwd=cwd, _run=_run)
181def ci_workflow_names(pr: int | str, *, cwd: str | None = None, _run=None) -> list[str] | None:
182 """The distinct **workflow** names that reported for ``pr``, or ``None`` on failure.
184 Deliberately not :func:`ci_check_names`. ``knobs.ci_workflows`` is keyed by the
185 *workflow* name (``CI``, ``CodeQL``), but the rollup reports *job* names — a
186 matrix job appears as ``test (py3.13 / ubuntu-latest)``, never as ``CI``. Asking
187 the presence question against job names would report every declared workflow
188 missing on a repo that uses a matrix, which is most of them.
190 ``workflowName`` is what a check run carries for this; legacy commit statuses have
191 none, so they fall back to ``context``/``name`` — a project that declares a bare
192 status-check name still matches.
193 """
194 jq = (
195 "[.statusCheckRollup[] "
196 '| (.workflowName | select(. != null and . != "")) '
197 '// (.context | select(. != null and . != "")) '
198 '// (.name | select(. != null and . != "")) '
199 "// empty] "
200 "| unique | .[]"
201 )
202 return _rollup_strings(pr, jq, cwd=cwd, _run=_run)
205def _rollup_strings(pr, jq: str, *, cwd: str | None, _run) -> list[str] | None:
206 result = run_argv(
207 ["gh", "pr", "view", str(pr), "--json", "statusCheckRollup", "--jq", jq],
208 cwd=cwd,
209 **_kw(_run),
210 )
211 if not result.ok:
212 return None
213 return [line.strip() for line in result.stdout.splitlines() if line.strip()]
216def merged_prs(
217 *, search: str | None = None, limit: int = 100, cwd: str | None = None, _run=None
218) -> CommandResult:
219 """List recently-merged PR numbers as a JSON array (``[{"number": N}, ...]``).
221 Thin I/O for ``capture-verify`` transport derivation: the authoritative
222 merged-PR set is read from the host instead of trusting the agent's args.
223 ``search`` narrows the set (e.g. ``"merged:>=2026-06-01"``). Fail-soft —
224 the caller inspects ``result.ok`` and degrades gracefully when offline.
225 """
226 argv = ["gh", "pr", "list", "--state", "merged", "--limit", str(limit), "--json", "number"]
227 if search:
228 argv += ["--search", search]
229 return run_argv(argv, cwd=cwd, **_kw(_run))
232def list_prs(
233 *, head: str | None = None, limit: int = 100, cwd: str | None = None, _run=None
234) -> CommandResult:
235 """List PRs (any state) as a JSON array (``[{"number": N, "headRefName": ...}, ...]``).
237 Thin I/O for dry-run integrity verification: the PRs that exist around a
238 rehearsed run are read from the host. ``head`` narrows to a specific head
239 branch. Fail-soft — the caller inspects ``result.ok`` and degrades to "no
240 PRs observed" when offline.
241 """
242 argv = [
243 "gh",
244 "pr",
245 "list",
246 "--state",
247 "all",
248 "--limit",
249 str(limit),
250 "--json",
251 "number,headRefName",
252 ]
253 if head:
254 argv += ["--head", head]
255 return run_argv(argv, cwd=cwd, **_kw(_run))
258def pr_labels(
259 pr: int | str,
260 *,
261 repo: str | None = None,
262 cwd: str | None = None,
263 _run=None,
264 _sleep=None,
265) -> list[str] | None:
266 """The label names currently on ``pr``, or ``None`` when ``gh`` could not be asked.
268 ``None`` is a fact about the runner, not the PR: callers that gate on a label must
269 treat it as "unknown" and go on, never as "no labels" (#1504). ``repo``
270 (``owner/name``) pins the read to the repository the caller's other reads use, so a
271 fork's PR with the same number is never read instead; the read is retried like
272 :func:`pr_files`, since a single ``gh`` blip would otherwise skip the early check.
273 """
274 argv = ["gh", "pr", "view", str(pr), "--json", "labels", "--jq", ".labels[].name"]
275 if repo:
276 argv += ["--repo", repo]
277 return _lines(argv, cwd=cwd, _run=_run, _sleep=_sleep)
280def pr_state(pr: int | str, *, cwd: str | None = None, _run=None) -> str | None:
281 """Live PR state as ``open`` / ``merged`` / ``closed``, or ``None`` when unreadable.
283 ``None`` is a fact about the **runner** (``gh`` missing, offline, no auth) and must
284 not be read as a fact about the PR — the caller maps it to ``unknown``, never to
285 ``missing``. A ``gh`` call that succeeds and reports no such PR is the only thing
286 that means the PR is gone.
287 """
288 result = run_argv(
289 ["gh", "pr", "view", str(pr), "--json", "state", "--jq", ".state"],
290 cwd=cwd,
291 **_kw(_run),
292 )
293 if not result.ok:
294 return None
295 raw = result.stdout.strip().lower()
296 return raw if raw in ("open", "merged", "closed") else None
299def pr_files(pr: int | str, *, cwd: str | None = None, _run=None, _sleep=None) -> list[str] | None:
300 """Paths the pull request changed — what it *meant* to change (#561).
302 Read from GitHub rather than from a local diff on purpose: after a squash-merge
303 the head branch is usually deleted, so the branch tip may not exist locally at
304 the moment this check runs. ``None`` when ``gh`` could not be asked.
305 """
306 return _lines(
307 ["gh", "pr", "view", str(pr), "--json", "files", "--jq", ".files[].path"],
308 cwd=cwd,
309 _run=_run,
310 _sleep=_sleep,
311 )
314def commit_files(sha: str, *, cwd: str | None = None, _run=None, _sleep=None) -> list[str] | None:
315 """Paths a commit changed against its first parent — what actually *landed*.
317 For a squash-merge the commit has one parent, so this is precisely the set of
318 files the merge wrote onto the base branch. ``None`` when ``gh`` could not be
319 asked; an empty list means the commit changed nothing, which is itself a fact.
320 """
321 return _lines(
322 ["gh", "api", f"repos/{{owner}}/{{repo}}/commits/{sha}", "--jq", ".files[].filename"],
323 cwd=cwd,
324 _run=_run,
325 _sleep=_sleep,
326 )
329def pr_added_lines(
330 pr: int | str, *, cwd: str | None = None, _run=None, _sleep=None
331) -> dict[str, list[str] | None] | None:
332 """Added lines per file in ``pr`` (#1511). ``None`` value marks an unverifiable file."""
333 rows = _json_rows(
334 ["gh", "api", f"repos/{{owner}}/{{repo}}/pulls/{pr}/files?per_page=100"],
335 cwd=cwd,
336 _run=_run,
337 _sleep=_sleep,
338 )
339 if rows is None:
340 return None
341 out: dict[str, list[str] | None] = {}
342 for row in rows:
343 path = str(row.get("filename") or "").strip()
344 if not path:
345 continue
346 patch = row.get("patch")
347 if row.get("status") not in ("added", "modified"):
348 out[path] = None
349 elif isinstance(patch, str):
350 out[path] = [line[1:] for line in patch.splitlines() if line.startswith("+")]
351 elif row.get("changes") == 0:
352 out[path] = []
353 else:
354 out[path] = None
355 return out
358def commit_file_content(
359 sha: str, path: str, *, cwd: str | None = None, _run=None, _sleep=None
360) -> str | None:
361 """UTF-8 file content at ``sha`` from GitHub's contents endpoint (<= 1 MB), or ``None``."""
362 quoted = urllib.parse.quote(path.lstrip("/"), safe="/")
363 data = rest_json(
364 run_argv_retry(
365 ["gh", "api", f"repos/{{owner}}/{{repo}}/contents/{quoted}?ref={sha}"],
366 cwd=cwd,
367 _run=_run,
368 _sleep=_sleep,
369 )
370 )
371 if (
372 not isinstance(data, dict)
373 or data.get("type") != "file"
374 or data.get("encoding") != "base64"
375 or not isinstance(data.get("content"), str)
376 ):
377 return None
378 try:
379 return base64.b64decode("".join(data["content"].split()), validate=True).decode("utf-8")
380 except (ValueError, UnicodeDecodeError):
381 return None
384def _lines(argv: list[str], *, cwd: str | None, _run, _sleep=None) -> list[str] | None:
385 """Read newline-separated ``gh`` output, retrying transient failures.
387 Routed through :func:`run_argv_retry` rather than :func:`run_argv`: the retry
388 was written, tested, and called by nothing (#938). These are the reads it was
389 written for — ``pr_files`` and ``commit_files`` — and one
390 ``keel verify-merge`` run makes ``4 + N`` of
391 them, N being the pull requests merged in the window (5–25 in this repo). Since
392 #936 made an unreadable input exit 2 instead of quietly passing, a single blip
393 on the busiest day produces a loud wrong answer, and a gate that cries wolf is
394 a gate that gets bypassed.
396 Retries only transient errors, so a persistent failure still returns ``None``
397 and still becomes ``unknown``. The retry must not become a slower way to
398 fail open.
399 """
400 result = run_argv_retry(argv, cwd=cwd, _run=_run, _sleep=_sleep)
401 if not result.ok:
402 return None
403 return [line.strip() for line in result.stdout.splitlines() if line.strip()]
406#: How far back one `gh pr list` page reaches. A window older than this many
407#: merges is reported as unreadable rather than empty — see #937 in the docstring
408#: below. Named so the ceiling is one place to read and one place to change.
409MERGED_PAGE_LIMIT = 100
412def prs_merged_between(
413 base: str,
414 since: str,
415 until: str,
416 *,
417 cwd: str | None = None,
418 _run=None,
419 _sleep=None,
420 limit: int = MERGED_PAGE_LIMIT,
421) -> list[int] | None:
422 """Pull request numbers merged into ``base`` in the half-open window (#561).
424 ``since``/``until`` are ISO-8601 timestamps. This is the window in which another
425 merge can land work that a branch created before ``since`` will not contain — the
426 precondition for an update-branch squash reverting it.
428 ``None`` when the answer could not be read — including when the page came back
429 **truncated**, which is #933's rule reached by a different mechanism (#937).
430 ``gh pr list`` returns the *newest* N merges, and the window filter used to run
431 inside ``--jq``, after that cut. On a repository where more than ``limit``
432 pull requests merged since the window closed, the window's merges are not in
433 the page at all, the filter matches nothing, and an empty list reads as
434 "nothing overtook this merge" — a successful read that saw none of the answer.
436 Live here, not latent: this repo has ~500 merged pull requests and
437 ``docs/keel/cli.md`` documents a retrospective ``verify-merge --pr 543`` on a
438 pull request from a previous month, which is exactly the shape that trips it.
440 Truncation is detectable because the page is newest-first: if it came back
441 **full** and its oldest entry still merged at or after ``since``, the page
442 never reached back far enough to contain the window. Paginating would also
443 work, but on a repo this size a retrospective check would walk hundreds of
444 pull requests to answer one question; saying "I could not see that far" is
445 honest and cheap. Raising ``limit`` is a separate tuning decision.
447 The filter therefore runs in Python rather than ``--jq``: the truncation
448 check needs the raw ``mergedAt`` values, which ``--jq`` had already discarded.
449 """
450 rows = _json_rows(
451 [
452 "gh",
453 "pr",
454 "list",
455 "--base",
456 base,
457 "--state",
458 "merged",
459 "--limit",
460 str(limit),
461 "--json",
462 "number,mergedAt",
463 ],
464 cwd=cwd,
465 _run=_run,
466 _sleep=_sleep,
467 )
468 if rows is None:
469 return None
470 merged_at = [str(row.get("mergedAt") or "") for row in rows]
471 if len(rows) >= limit and merged_at and min(merged_at) >= since:
472 # Full page whose oldest entry is still inside/after the window: the read
473 # succeeded and saw only part of the answer, which must not read as clean.
474 return None
475 return [
476 int(row["number"])
477 for row in rows
478 if isinstance(row.get("number"), int) and since < str(row.get("mergedAt") or "") < until
479 ]
482def _json_rows(argv: list[str], *, cwd: str | None, _run, _sleep=None) -> list[dict] | None:
483 """Parse ``gh --json`` output into rows, or ``None`` when it could not be read."""
484 result = run_argv_retry(argv, cwd=cwd, _run=_run, _sleep=_sleep)
485 if not result.ok:
486 return None
487 try:
488 data = json.loads(result.stdout or "[]")
489 except ValueError:
490 return None
491 return data if isinstance(data, list) else None
494def _merge_window_fields(result: CommandResult) -> list[str]:
495 """The four TSV fields of a ``pr_merge_window`` read, trailing blank preserved.
497 Trims newlines only. ``str.strip()`` also removes the trailing tab, so a merged
498 PR whose ``mergeCommit.oid`` has not appeared yet arrives as three fields and
499 reads as malformed rather than as "not settled yet" — which is precisely the
500 state the poll above exists to recognise (#938).
501 """
502 return result.stdout.strip("\r\n").split("\t")
505#: Reads of a just-merged PR before GitHub has populated ``mergeCommit.oid``.
506#: Three attempts a second apart: the field settles in well under a second in
507#: practice, and the cap matters more than the ceiling — this runs immediately
508#: after an irreversible merge, so it must give up rather than hang (#938).
509MERGE_COMMIT_POLL_ATTEMPTS = 3
510MERGE_COMMIT_POLL_DELAY_S = 1.0
513def pr_merge_window(
514 pr: int | str, *, cwd: str | None = None, _run=None, _sleep=None
515) -> dict | None:
516 """When a PR branched and merged, its base, and the SHA it merged as (#561).
518 ``createdAt`` stands in for the branch point. It is the conservative choice: a
519 branch is cut at or before its PR is opened, so the window can only be too wide,
520 never too narrow — a wider window over-reports rather than missing a revert.
522 ``None`` when ``gh`` cannot be asked or the PR is not merged.
524 A merged PR whose ``mergeCommit.oid`` has not appeared yet is **polled** for,
525 briefly, rather than read as absent. ``ship.md`` tells the operator to run the
526 drift check "immediately after a successful merge" — the one moment the field
527 is least likely to be populated — and since #936 an unreadable input exits 2.
528 Without the poll the runbook's own timing is the most frequent trigger of the
529 loud path, and the shipped remedy is a sentence of prose asking an agent to
530 retry (#938). Bounded, and giving up still yields ``None``: the poll must not
531 become a way to eventually pass.
532 """
533 # Named rather than written as two adjacent literals inside the argv list: an
534 # implicit concatenation there reads as a possible missing comma (CodeQL flags it),
535 # and an argv list is exactly where that ambiguity is expensive.
536 jq = '[.createdAt, .mergedAt, .baseRefName, (.mergeCommit.oid // "")] | @tsv'
537 argv = [
538 "gh",
539 "pr",
540 "view",
541 str(pr),
542 "--json",
543 "createdAt,mergedAt,baseRefName,mergeCommit",
544 "--jq",
545 jq,
546 ]
547 sleep_fn = _sleep or time.sleep
548 for attempt in range(1, MERGE_COMMIT_POLL_ATTEMPTS + 1):
549 result = run_argv_retry(argv, cwd=cwd, _run=_run, _sleep=_sleep)
550 # Only newlines are trimmed. `.strip()` also eats the trailing tab, which is
551 # the very field being waited on — an empty SHA would arrive as three fields
552 # and read as malformed rather than as "not settled yet".
553 parts = _merge_window_fields(result) if result.ok else []
554 # Poll only the settling case: merged (first three fields present) with the
555 # SHA still empty. An unmerged PR or an unreadable `gh` is a real answer, and
556 # waiting on either would just make every such call three seconds slower.
557 settling = len(parts) == 4 and all(parts[:3]) and not parts[3]
558 if not settling:
559 break
560 if attempt < MERGE_COMMIT_POLL_ATTEMPTS:
561 sleep_fn(MERGE_COMMIT_POLL_DELAY_S)
562 if not result.ok:
563 return None
564 parts = _merge_window_fields(result)
565 if len(parts) != 4 or not all(parts[:3]) or not parts[3]:
566 return None
567 return {
568 "branched_at": parts[0],
569 "merged_at": parts[1],
570 "base": parts[2],
571 "merge_commit": parts[3],
572 }
575def pr_merge_snapshot(pr: int | str, *, cwd: str | None = None, _run=None) -> CommandResult:
576 return run_argv(
577 [
578 "gh",
579 "pr",
580 "view",
581 str(pr),
582 "--json",
583 "headRefOid,headRefName,mergeStateStatus,statusCheckRollup",
584 ],
585 cwd=cwd,
586 **_kw(_run),
587 )
590def merge_pr(
591 pr: int | str,
592 *,
593 method: str = "squash",
594 head_sha: str | None = None,
595 cwd: str | None = None,
596 _run=None,
597) -> CommandResult:
598 """Merge the pull request over GraphQL, pinned to ``head_sha`` when one is known.
600 ``--match-head-commit`` is this transport's spelling of the pin :func:`rest_merge_pr`
601 sends as ``sha``: GitHub refuses the merge if the head is not that commit. Without it
602 the head could move between the checks `keel merge` ran and this call, and the merge
603 would land whatever it moved to.
604 """
605 argv = ["gh", "pr", "merge", str(pr), f"--{method}"]
606 if head_sha:
607 argv += ["--match-head-commit", head_sha]
608 return run_argv(argv, cwd=cwd, **_kw(_run))
611def _run_id_of(link: object) -> str | None:
612 """The GitHub Actions run id in a check's details link, or ``None``."""
613 match = re.search(r"/actions/runs/(\d+)", link) if isinstance(link, str) else None
614 return match.group(1) if match else None
617def failed_check_runs(
618 pr: int | str, names: Sequence[str], *, cwd: str | None = None, _run=None
619) -> tuple[dict[str, str], str | None]:
620 """``({name: run id}, error)`` for the failed checks called exactly ``names``.
622 The checks are found through ``gh pr checks``, whose details link names the Actions run.
623 ``gh pr checks`` exits non-zero when a check is pending or failing but still prints the
624 rows, so stdout is read whatever the exit code; empty stdout *with* a failing exit is an
625 error (authentication, network), not an empty listing. A cancelled or timed-out job
626 (``cancel``) counts as failed. A check with no Actions run (a third-party status) cannot
627 be rerun here. Several names can share one run, which is why the caller reruns by run id.
628 """
629 listed = run_argv(
630 ["gh", "pr", "checks", str(pr), "--json", "name,link,bucket"], cwd=cwd, **_kw(_run)
631 )
632 try:
633 rows = json.loads(listed.stdout) if listed.stdout.strip() else ([] if listed.ok else None)
634 except ValueError:
635 rows = None
636 if not isinstance(rows, list):
637 return {}, f"could not list the checks of PR #{pr}: {listed.output.strip()}"
638 runs: dict[str, str] = {}
639 for name in names:
640 for row in rows:
641 if (
642 isinstance(row, dict)
643 and row.get("name") == name
644 and row.get("bucket") in ("fail", "cancel")
645 and _run_id_of(row.get("link"))
646 ):
647 runs[name] = str(_run_id_of(row.get("link")))
648 break
649 else:
650 return {}, f"no failed GitHub Actions run found for check {name!r}"
651 return runs, None
654def rerun_run(run_id: str, *, cwd: str | None = None, _run=None) -> tuple[bool, str]:
655 """Rerun the failed jobs of one Actions run: ``(ok, detail)``."""
656 result = run_argv(["gh", "run", "rerun", run_id, "--failed"], cwd=cwd, **_kw(_run))
657 if not result.ok:
658 return False, f"gh run rerun {run_id} failed: {result.output.strip()}"
659 return True, f"reran the failed jobs of run {run_id}"
662def comment(pr: int | str, body: str, *, cwd: str | None = None, _run=None) -> CommandResult:
663 return run_argv(["gh", "pr", "comment", str(pr), "--body", body], cwd=cwd, **_kw(_run))
666def post_issue_comment(
667 owner_repo: str,
668 issue_or_pr: int | str,
669 body: str,
670 *,
671 cwd: str | None = None,
672 _run=None,
673) -> CommandResult:
674 return run_argv(
675 [
676 "gh",
677 "api",
678 f"repos/{owner_repo}/issues/{issue_or_pr}/comments",
679 "-X",
680 "POST",
681 "-F",
682 f"body={body}",
683 ],
684 cwd=cwd,
685 **_kw(_run),
686 )
689def create_issue(
690 owner_repo: str,
691 title: str,
692 body: str,
693 *,
694 cwd: str | None = None,
695 _run=None,
696) -> CommandResult:
697 """Open one issue over REST; the response JSON names its ``number`` and ``html_url``.
699 ``-f``, never ``-F``, for the same reason as :func:`issue_labels_add_argv`: ``-F``
700 reads a value starting with ``@`` as a file path, and a title or body is text.
701 Mutating — callers gate it on operator consent.
702 """
703 return run_argv(
704 [
705 "gh",
706 "api",
707 f"repos/{owner_repo}/issues",
708 "-X",
709 "POST",
710 "-f",
711 f"title={title}",
712 "-f",
713 f"body={body}",
714 ],
715 cwd=cwd,
716 **_kw(_run),
717 )
720def edit_issue_comment(
721 owner_repo: str,
722 comment_id: int | str,
723 body: str,
724 *,
725 cwd: str | None = None,
726 _run=None,
727) -> CommandResult:
728 return run_argv(
729 [
730 "gh",
731 "api",
732 f"repos/{owner_repo}/issues/comments/{comment_id}",
733 "-X",
734 "PATCH",
735 "-F",
736 f"body={body}",
737 ],
738 cwd=cwd,
739 **_kw(_run),
740 )
743def close_issue(
744 issue: int | str,
745 *,
746 cwd: str | None = None,
747 repo: str | None = None,
748 reason: str | None = None,
749 _run=None,
750) -> CommandResult:
751 """``gh issue close``; ``repo`` names the repository, ``reason`` the state reason.
753 ``swarm-land`` closes a landed cluster's issues as ``completed`` in the configured
754 ``owner/repo`` (#1422) rather than whatever repository the checkout's remote names.
755 """
756 argv = ["gh", "issue", "close", str(issue)]
757 if repo:
758 argv += ["--repo", repo]
759 if reason:
760 argv += ["--reason", reason]
761 return run_argv(argv, cwd=cwd, **_kw(_run))
764def issue_facts(
765 issue: int | str,
766 *,
767 cwd: str | None = None,
768 fields: str = "title,labels",
769 _run=None,
770) -> CommandResult:
771 """Fetch an issue's ``title`` and ``labels`` as JSON for ``keel guard``.
773 Thin I/O for blocker evaluation: the issue facts are read from the host
774 rather than trusting agent-supplied args. Fail-soft — the caller inspects
775 ``result.ok`` and falls back to offline args when offline.
777 ``fields`` widens the same call for the capture sink, which needs the body
778 too. It stays a parameter rather than a second function so both readers make
779 the identical request and a change to one is a change to both.
780 """
781 return run_argv(
782 ["gh", "issue", "view", str(issue), "--json", fields],
783 cwd=cwd,
784 **_kw(_run),
785 )
788#: Labels read in one page. GitHub's default is 30; a policy pack plus keel's
789#: attribution vocabulary exceeds that on any real repository, and a truncated
790#: listing would report labels as missing that exist.
791LABEL_PAGE_LIMIT = 500
794def label_list_argv(repo: str | None = None) -> list[str]:
795 """The exact ``gh label list`` command ``keel doctor`` runs (pure, for tests)."""
796 argv = ["gh", "label", "list", "--limit", str(LABEL_PAGE_LIMIT), "--json", "name"]
797 return argv + ["--repo", repo] if repo else argv
800def list_labels(*, repo: str | None = None, cwd: str | None = None, _run=None) -> CommandResult:
801 """List a repository's labels as JSON. Fail-soft: the caller reads ``result.ok``."""
802 return run_argv(label_list_argv(repo), cwd=cwd, **_kw(_run))
805#: Seconds ``keel doctor`` waits for ``gh auth status`` — one round trip to GitHub.
806AUTH_STATUS_TIMEOUT_S = 10
809def auth_status(*, cwd: str | None = None, _run=None) -> CommandResult:
810 """``gh auth status``: is ``gh`` logged in? Fail-soft; the caller reads ``result.ok``.
812 Read-only (no ``--show-token``), so its output names the account, never the token.
813 """
814 return run_argv(["gh", "auth", "status"], cwd=cwd, timeout=AUTH_STATUS_TIMEOUT_S, **_kw(_run))
817def label_create_argv(name: str, repo: str | None = None) -> list[str]:
818 """The exact ``gh label create`` command for one label.
820 Built here, in the one module that owns keel's ``gh`` command shapes, so the command
821 ``keel doctor`` *prints* for an operator to paste and the command ``--fix`` *runs*
822 are the same string and cannot drift apart.
823 """
824 argv = ["gh", "label", "create", name]
825 return argv + ["--repo", repo] if repo else argv
828def create_label(
829 name: str, *, repo: str | None = None, cwd: str | None = None, _run=None
830) -> CommandResult:
831 """Create one repository label. Mutating — callers gate it on operator consent."""
832 return run_argv(label_create_argv(name, repo), cwd=cwd, **_kw(_run))
835def issue_labels_add_argv(owner_repo: str, number: int, labels: Sequence[str]) -> list[str]:
836 """The exact REST call that adds ``labels`` to issue or pull request ``number``.
838 ``-f``, never ``-F``: ``-F`` reads a value starting with ``@`` as a file path, and a
839 label is a name, not a file. Over REST, like :func:`post_issue_comment`, so a host that
840 blocks GraphQL can still label the pull request it opened.
841 """
842 argv = ["gh", "api", f"repos/{owner_repo}/issues/{number}/labels", "-X", "POST"]
843 for label in labels:
844 argv += ["-f", f"labels[]={label}"]
845 return argv
848def add_issue_labels(
849 owner_repo: str,
850 number: int,
851 labels: Sequence[str],
852 *,
853 cwd: str | None = None,
854 _run=None,
855) -> CommandResult:
856 """Add ``labels`` to issue or pull request ``number``. Mutating, and fail-soft."""
857 return run_argv(issue_labels_add_argv(owner_repo, number, labels), cwd=cwd, **_kw(_run))
860def _kw(_run):
861 return {"_run": _run} if _run is not None else {}
864# --- REST transport (#1175) -------------------------------------------------
865#
866# `gh pr view --json` and `gh pr merge` both go over GitHub's **GraphQL** endpoint.
867# On a host whose egress proxy allows the REST API and blocks GraphQL — the remote
868# environment #1169/#1170/#1171 were shipped from — every one of them fails before
869# `keel merge` reaches its claim, its window re-check, its CI rollup or its evidence
870# verification, and the operator is pushed off the only sanctioned merge path onto a
871# hand-driven squash. These are the same reads and the same write, asked over REST.
872#
873# `gh api` expands `{owner}` and `{repo}` from the checkout's own remote, so none of
874# this needs the project config — which matters for `keel verify-merge`, whose whole
875# contract is that it reads GitHub and nothing else.
877#: A query that costs nothing and proves only that the endpoint answers at all.
878_GRAPHQL_PROBE = ["gh", "api", "graphql", "-f", "query=query{__typename}"]
881def graphql_available(*, cwd: str | None = None, _run=None) -> bool:
882 """Can this host reach GitHub's GraphQL endpoint?
884 Probed once per run and reused, because the answer is a property of the *host*
885 (its proxy) rather than of any pull request. A blocked endpoint fails the probe
886 the same way it fails a real query — a non-zero exit, usually carrying a proxy's
887 403 or 405 — so the probe needs no special-casing of the reason.
889 Deliberately **not** a fallback after a failed call. Reads could retry safely;
890 `gh pr merge` cannot. A merge that failed for an unknown reason may or may not
891 have landed, and re-driving it over a second transport is how a pull request gets
892 merged twice. The transport is chosen before anything is attempted.
893 """
894 return run_argv(_GRAPHQL_PROBE, cwd=cwd, **_kw(_run)).ok
897def rest_pull(pr: int | str, *, cwd: str | None = None, _run=None) -> CommandResult:
898 """The pull request as REST returns it (``head.sha``, ``mergeable_state``, …)."""
899 return run_argv(["gh", "api", f"repos/{{owner}}/{{repo}}/pulls/{pr}"], cwd=cwd, **_kw(_run))
902def rest_check_runs(sha: str, *, cwd: str | None = None, _run=None) -> CommandResult:
903 """Check runs for one commit — the Actions half of a status-check rollup."""
904 return run_argv(
905 [
906 "gh",
907 "api",
908 "--paginate",
909 f"repos/{{owner}}/{{repo}}/commits/{sha}/check-runs?per_page=100",
910 ],
911 cwd=cwd,
912 **_kw(_run),
913 )
916def rest_commit_statuses(sha: str, *, cwd: str | None = None, _run=None) -> CommandResult:
917 """Commit statuses for one commit — the other half, for non-Actions CI."""
918 return run_argv(
919 [
920 "gh",
921 "api",
922 "--paginate",
923 f"repos/{{owner}}/{{repo}}/commits/{sha}/statuses?per_page=100",
924 ],
925 cwd=cwd,
926 **_kw(_run),
927 )
930def rest_json(result: CommandResult) -> object | None:
931 """Parse a `gh api` body, tolerating `--paginate`'s concatenated pages."""
932 if not result.ok:
933 return None
934 text = (result.stdout or "").strip()
935 if not text:
936 return None
937 try:
938 return json.loads(text)
939 except json.JSONDecodeError:
940 pass
941 # `gh api --paginate` concatenates one JSON document per page rather than merging
942 # them, so a two-page read is `[…][…]` and is not a document at all. Decoding them
943 # one at a time is what the flag actually returns, and a reader that only tried
944 # `json.loads` saw the second page as a syntax error and reported "no checks".
945 decoder, index, pages = json.JSONDecoder(), 0, []
946 while index < len(text):
947 try:
948 page, index = decoder.raw_decode(text, index)
949 except json.JSONDecodeError:
950 return None
951 pages.append(page)
952 while index < len(text) and text[index] in " \t\r\n":
953 index += 1
954 # `pages` cannot be empty here: `text` is non-empty and stripped, so the loop ran at
955 # least once and either appended a page or returned. A guard for it would be a branch
956 # no input can take, which is a claim about the code that the tests cannot check.
957 if all(isinstance(page, list) for page in pages):
958 return [item for page in pages for item in page]
959 return pages[0] if len(pages) == 1 else pages
962def _check_run_rows(payload: object) -> list[dict]:
963 """The check runs inside a `commits/<sha>/check-runs` body, across every page.
965 That endpoint answers with an **object** — ``{"total_count": N, "check_runs": [...]}``
966 — not with a bare array, and `gh api --paginate` concatenates one such object per
967 page. So a head with more than a hundred checks arrives as ``{…}{…}``, which
968 :func:`rest_json` correctly reports as *a list of two page objects*.
970 Read as a list of check runs, those two objects became two entries with no ``name``,
971 no ``status`` and no ``conclusion`` — neither a failure nor pending, so the reducer
972 counted them as checks that had reported and returned **pass**. A merge gate handed
973 an all-green rollup for a head whose hundred-odd real checks were never looked at.
975 Only the documented shape contributes. A payload that is neither the object nor
976 pages of it yields nothing, and the caller treats an empty rollup as *no checks have
977 reported*, which refuses a non-docs merge rather than passing it.
978 """
979 pages = payload if isinstance(payload, list) else [payload]
980 rows: list[dict] = []
981 for page in pages:
982 if not isinstance(page, dict):
983 continue
984 runs = page.get("check_runs")
985 if isinstance(runs, list):
986 rows.extend(run for run in runs if isinstance(run, dict))
987 return rows
990def rest_rollup(check_runs: object, statuses: object) -> list[dict]:
991 """The two REST payloads in the shape ``statusCheckRollup`` has.
993 Pure, and a translation rather than a judgement: the rollup reducer reads
994 ``name``/``context``, ``status``, ``conclusion`` and the two timestamps, and
995 GraphQL spells those in SCREAMING_CASE where REST spells them in lower. Keeping
996 the translation here means the reducer, the dedupe and the recency ordering are
997 one implementation asked the same question over either transport, instead of two
998 that agree until they do not.
1000 Commit statuses are carried through with their ``context`` and ``state``, which is
1001 what the GraphQL rollup returns for a ``StatusContext`` and what the reducer reads
1002 from one (#1202). They are included rather than dropped for two reasons: a failing
1003 status has to be able to *fail* a merge, and even a passing one makes the rollup
1004 non-empty, which is the difference between ``pass`` and ``no-checks``.
1005 """
1006 entries: list[dict] = []
1007 # `_check_run_rows` has already dropped every non-object, so nothing is re-checked
1008 # here: a guard no input can trip is a claim about the data the tests cannot make.
1009 for run in _check_run_rows(check_runs):
1010 entries.append(
1011 {
1012 "name": run.get("name"),
1013 "status": _upper(run.get("status")),
1014 "conclusion": _upper(run.get("conclusion")),
1015 "startedAt": run.get("started_at"),
1016 "completedAt": run.get("completed_at"),
1017 }
1018 )
1019 for row in _status_rows(statuses):
1020 # **Carried through, not translated.** A commit status keeps its verdict in
1021 # `state`, exactly as the GraphQL rollup returns one, because the reducer reads
1022 # that field now (#1202). #1175 translated it here instead, which worked and left
1023 # the two wires speaking different shapes — and the GraphQL one, which is the
1024 # default nearly every run takes, still counted a *failing* status as a check
1025 # that had reported. The timestamps come along because dedupe orders by them.
1026 entries.append(
1027 {
1028 "context": row.get("context"),
1029 "state": _upper(row.get("state")),
1030 "completedAt": row.get("updated_at"),
1031 "startedAt": row.get("created_at"),
1032 }
1033 )
1034 return entries
1037def _status_rows(payload: object) -> list[dict]:
1038 """The rows of a `commits/<sha>/statuses` body, across every page.
1040 That endpoint *does* answer with an array, so `--paginate` yields a list of pages —
1041 which :func:`rest_json` flattens — or a single page's list. Both arrive here as a
1042 list of row objects; anything else contributes nothing.
1043 """
1044 rows = payload if isinstance(payload, list) else []
1045 return [row for row in rows if isinstance(row, dict)]
1048def _upper(value: object) -> str | None:
1049 """``value`` upper-cased when it is a string; ``None`` otherwise.
1051 REST says ``in_progress`` and ``success`` where GraphQL says ``IN_PROGRESS`` and
1052 ``SUCCESS``; the two differ in case alone, so upper-casing *is* the translation.
1053 """
1054 return value.upper() if isinstance(value, str) else None
1057def rest_merge_pr(
1058 pr: int | str,
1059 *,
1060 method: str = "squash",
1061 head_sha: str | None = None,
1062 cwd: str | None = None,
1063 _run=None,
1064) -> CommandResult:
1065 """Merge the pull request over REST, pinned to ``head_sha`` when one is known.
1067 ``sha`` is REST's own head-pin: the merge is refused if the pull request has moved
1068 since it was read. `gh pr merge` applies none by default; :func:`merge_pr` passes
1069 ``--match-head-commit`` for the same pin, so the two transports are equally strict —
1070 deliberately, because a merge is the one operation here that cannot be taken back.
1071 """
1072 argv = [
1073 "gh",
1074 "api",
1075 "-X",
1076 "PUT",
1077 f"repos/{{owner}}/{{repo}}/pulls/{pr}/merge",
1078 "-f",
1079 f"merge_method={method}",
1080 ]
1081 if head_sha:
1082 argv += ["-f", f"sha={head_sha}"]
1083 return run_argv(argv, cwd=cwd, **_kw(_run))
1086def rest_pr_files(
1087 pr: int | str, *, cwd: str | None = None, _run=None, _sleep=None
1088) -> list[str] | None:
1089 """Paths the pull request changed, over REST. ``None`` when unreadable."""
1090 return _lines(
1091 [
1092 "gh",
1093 "api",
1094 "--paginate",
1095 f"repos/{{owner}}/{{repo}}/pulls/{pr}/files?per_page=100",
1096 "--jq",
1097 ".[].filename",
1098 ],
1099 cwd=cwd,
1100 _run=_run,
1101 _sleep=_sleep,
1102 )
1105def _rest_commit_on_branch(sha: str, base: str, *, cwd: str | None, _run) -> bool:
1106 """Is ``sha`` an ancestor of ``base`` — that is, did this commit actually land?
1108 ``compare/<base>...<sha>`` answers ``identical`` when they are the same commit and
1109 ``behind`` when ``sha`` is reachable from ``base``; ``ahead`` and ``diverged`` are
1110 the speculative test merge, which exists as an object and is on no branch.
1111 """
1112 if not sha or not base:
1113 return False
1114 result = run_argv(
1115 [
1116 "gh",
1117 "api",
1118 f"repos/{{owner}}/{{repo}}/compare/{base}...{sha}",
1119 "--jq",
1120 ".status",
1121 ],
1122 cwd=cwd,
1123 **_kw(_run),
1124 )
1125 return result.ok and result.stdout.strip() in ("identical", "behind")
1128def rest_pr_merge_window(
1129 pr: int | str, *, cwd: str | None = None, _run=None, _sleep=None
1130) -> dict | None:
1131 """``branched_at`` / ``merged_at`` / ``base`` / ``merge_commit`` over REST.
1133 The same four fields :func:`pr_merge_window` returns, and the same settling poll:
1134 a pull request reports ``merged_at`` before ``merge_commit_sha`` is populated, and
1135 reading it in that instant is how the drift check comes back "no merge commit yet"
1136 for a merge that had just happened.
1137 """
1138 sleep_fn = _sleep or time.sleep
1139 for attempt in range(1, MERGE_COMMIT_POLL_ATTEMPTS + 1):
1140 payload = rest_json(
1141 run_argv_retry(
1142 ["gh", "api", f"repos/{{owner}}/{{repo}}/pulls/{pr}"],
1143 cwd=cwd,
1144 _run=_run,
1145 _sleep=_sleep,
1146 )
1147 )
1148 if not isinstance(payload, dict):
1149 return None
1150 window = {
1151 "branched_at": str(payload.get("created_at") or ""),
1152 "merged_at": str(payload.get("merged_at") or ""),
1153 "base": str((payload.get("base") or {}).get("ref") or ""),
1154 "merge_commit": str(payload.get("merge_commit_sha") or ""),
1155 }
1156 # **Reachability, not presence.** REST's `merge_commit_sha` is not empty while a
1157 # pull request is open: GitHub documents it as the *speculative test-merge* SHA
1158 # (`refs/pull/<n>/merge`) until the merge lands, when it becomes the commit that
1159 # actually landed. So "merged and the field is filled" is true on the first
1160 # post-merge read even while the cached test SHA is still being served — and the
1161 # drift check would then judge the test merge instead of the squash. GraphQL's
1162 # `mergeCommit.oid` is null until the real commit exists, which is why the same
1163 # poll is correct there and not here.
1164 settling = window["merged_at"] and not _rest_commit_on_branch(
1165 window["merge_commit"], window["base"], cwd=cwd, _run=_run
1166 )
1167 if settling:
1168 if attempt < MERGE_COMMIT_POLL_ATTEMPTS:
1169 sleep_fn(MERGE_COMMIT_POLL_DELAY_S)
1170 continue
1171 # Still unsettled when the budget runs out: the SHA on offer is one this
1172 # check could not find on the base branch, so it is not an answer. Returning
1173 # it anyway is how the drift read would judge the speculative test merge.
1174 return None
1175 # **All four, exactly as the GraphQL reader requires.** REST answers an
1176 # *unmerged* pull request with `created_at` and `base.ref` and a null
1177 # `merged_at`, so "any field present" reported a window for one — and a caller
1178 # that supplied `--merge-sha` then went on to judge drift on a merge that had
1179 # not happened, where the same call over GraphQL says `unknown`.
1180 return window if all(window.values()) else None
1181 return None # pragma: no cover - the loop always returns on its last attempt
1184def rest_prs_merged_between(
1185 base: str,
1186 since: str,
1187 until: str,
1188 *,
1189 cwd: str | None = None,
1190 _run=None,
1191 _sleep=None,
1192 limit: int = MERGED_PAGE_LIMIT,
1193) -> list[int] | None:
1194 """:func:`prs_merged_between` over REST, with the same truncation honesty.
1196 REST cannot sort by merge time — ``sort`` takes ``created``, ``updated``,
1197 ``popularity`` and ``long-running``, and nothing else — so the page is ordered by
1198 ``updated`` descending and the truncation rule is re-derived on that key rather
1199 than transplanted. It still holds, and for a reason worth writing down: merging a
1200 pull request *updates* it, so ``merged_at <= updated_at`` for every row. If the
1201 oldest row this page reached was updated before ``since``, every row it did not
1202 reach was updated earlier still, so it was merged earlier still, so it is outside
1203 the window and the window was seen whole. If it was not, the page may have stopped
1204 short of the answer — and a partial read must not render as "nothing overtook this
1205 merge" (#933, #937).
1207 ``state=closed`` is the narrowest REST offers; a closed-unmerged row has no
1208 ``merged_at``, is filtered out, and costs only a slot in the page.
1209 """
1210 rows = rest_json(
1211 run_argv_retry(
1212 [
1213 "gh",
1214 "api",
1215 f"repos/{{owner}}/{{repo}}/pulls"
1216 f"?base={base}&state=closed&sort=updated&direction=desc&per_page={limit}",
1217 ],
1218 cwd=cwd,
1219 _run=_run,
1220 _sleep=_sleep,
1221 )
1222 )
1223 if not isinstance(rows, list):
1224 return None
1225 updated = [str(row.get("updated_at") or "") for row in rows if isinstance(row, dict)]
1226 if len(rows) >= limit and updated and min(updated) >= since:
1227 return None
1228 return [
1229 int(row["number"])
1230 for row in rows
1231 if isinstance(row, dict)
1232 and isinstance(row.get("number"), int)
1233 and since < str(row.get("merged_at") or "") < until
1234 ]