Add list_check_runs_for_ref to the GitHub client (#96)

Adds a `list_check_runs_for_ref` method to the GitHub client that hits
`GET /repos/{owner}/{repo}/commits/{ref}/check-runs` to fetch check runs
for a commit SHA (or git ref).

This will allow us to go from PR number to the latest check runs in just
two steps:

- `/repos/{owner}/{repo}/pulls/{pull_number}` -> we can get the
`head.sha` to get the head commit SHA

- `/repos/{owner}/{repo}/commits/{head.sha}/check-runs?filter=latest` ->
we can filter by the latest check run, essentially the latest check
suite

part of CW-1428

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: alexsohn1126

bin/github-client

@@ -97,8 +97,8 @@ from scm.types import (
     DeleteCommitAction,
     DownloadArchiveProtocol,
     GetAppInstallationProtocol,
-    GetAuthenticatedActorProtocol,
     GetArchiveLinkProtocol,
+    GetAuthenticatedActorProtocol,
     GetBranchProtocol,
     GetCheckRunProtocol,
     GetCommitChangesProtocol,
@@ -126,6 +126,7 @@ from scm.types import (
     GetRepositoryTopicsProtocol,
     GetRepositoryUserPermissionProtocol,
     GetReviewCommentsProtocol,
+    ListCheckRunsForRefProtocol,
     ListCheckRunsInCheckSuiteProtocol,
     ListRepositoriesProtocol,
     ListRepositoryUserPermissionsProtocol,
@@ -333,6 +334,14 @@ def main() -> None:
     p.add_argument("--cursor", type=int, default=None)
     p.add_argument("--per-page", type=int, default=None)
 
+    p = sub.add_parser("list-check-runs-for-ref")
+    p.add_argument("ref")
+    p.add_argument("--check-name", default=None)
+    p.add_argument("--status", choices=["queued", "in_progress", "completed"], default=None)
+    p.add_argument("--filter", choices=["latest", "all"], default=None)
+    p.add_argument("--cursor", type=int, default=None)
+    p.add_argument("--per-page", type=int, default=None)
+
     p = sub.add_parser("get-branch")
     p.add_argument("name")
 
@@ -575,6 +584,23 @@ def main() -> None:
             )
         )
 
+    elif args.command == "list-check-runs-for-ref":
+        assert isinstance(scm, ListCheckRunsForRefProtocol)
+        pagination: PaginationParams = {}
+        if args.cursor is not None:
+            pagination["cursor"] = args.cursor
+        if args.per_page is not None:
+            pagination["per_page"] = args.per_page
+        dump(
+            scm.list_check_runs_for_ref(
+                args.ref,
+                check_name=args.check_name,
+                status=args.status,
+                timestamp_filter=args.filter,
+                pagination=pagination or None,
+            )
+        )
+
     elif args.command == "get-branch":
         assert isinstance(scm, GetBranchProtocol)
         dump(scm.get_branch(args.name))

src/scm/actions.py

@@ -102,6 +102,7 @@
     Issue,
     IssueState,
     Label,
+    ListCheckRunsForRefProtocol,
     ListCheckRunsInCheckSuiteProtocol,
     ListRepositoriesProtocol,
     ListRepositoryUserPermissionsProtocol,
@@ -850,6 +851,25 @@ def list_check_runs_in_check_suite(
     )
 
 
+def list_check_runs_for_ref(
+    scm: ListCheckRunsForRefProtocol,
+    ref: str,
+    check_name: str | None = None,
+    status: Literal["queued", "in_progress", "completed"] | None = None,
+    timestamp_filter: Literal["latest", "all"] = "latest",
+    pagination: PaginationParams | None = None,
+    request_options: RequestOptions | None = None,
+) -> PaginatedActionResult[list[CheckRun]]:
+    return scm.list_check_runs_for_ref(
+        ref,
+        check_name=check_name,
+        status=status,
+        timestamp_filter=timestamp_filter,
+        pagination=pagination,
+        request_options=request_options,
+    )
+
+
 def minimize_comment(scm: MinimizeCommentProtocol, comment_node_id: str, reason: str) -> None:
     return scm.minimize_comment(comment_node_id, reason)
 
@@ -978,6 +998,7 @@ def download_archive(
     "get_repository_topics",
     "get_thread_id_from_review_comment_unique_id",
     "get_tree",
+    "list_check_runs_for_ref",
     "list_repository_user_permissions",
     "list_repositories",
     "minimize_comment",

src/scm/providers/github/provider.py

@@ -1589,6 +1589,31 @@ def list_check_runs_in_check_suite(
         )
         return map_paginated_action(pagination, response, lambda r: [map_check_run(f) for f in r["check_runs"]])
 
+    def list_check_runs_for_ref(
+        self,
+        ref: str,
+        check_name: str | None = None,
+        status: Literal["queued", "in_progress", "completed"] | None = None,
+        timestamp_filter: Literal["latest", "all"] = "latest",
+        pagination: PaginationParams | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> PaginatedActionResult[list[CheckRun]]:
+        params: dict[str, Any] = {}
+        if check_name is not None:
+            params["check_name"] = check_name
+        if status is not None:
+            params["status"] = status
+        if timestamp_filter is not None:
+            params["filter"] = timestamp_filter
+
+        response = self.get(
+            f"/repos/{self.repository['name']}/commits/{ref}/check-runs",
+            params=params,
+            pagination=pagination,
+            request_options=request_options,
+        )
+        return map_paginated_action(pagination, response, lambda r: [map_check_run(f) for f in r["check_runs"]])
+
     def get_archive_link(
         self,
         ref: str,

src/scm/types.py

@@ -1253,6 +1253,19 @@ def list_check_runs_in_check_suite(
     ) -> PaginatedActionResult[list[CheckRun]]: ...
 
 
+@runtime_checkable
+class ListCheckRunsForRefProtocol(Protocol):
+    def list_check_runs_for_ref(
+        self,
+        ref: str,
+        check_name: str | None = None,
+        status: Literal["queued", "in_progress", "completed"] | None = None,
+        timestamp_filter: Literal["latest", "all"] = "latest",
+        pagination: PaginationParams | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> PaginatedActionResult[list[CheckRun]]: ...
+
+
 # Review Protocols
 
 
@@ -1463,6 +1476,7 @@ def update_and_collapse_pull_request_comment(
     GetTreeProtocol,
     ListRepositoriesProtocol,
     ListCheckRunsInCheckSuiteProtocol,
+    ListCheckRunsForRefProtocol,
     MinimizeCommentProtocol,
     RequestReviewProtocol,
     ResolveReviewThreadProtocol,

tests/unit/provider/test_github.py

@@ -721,6 +721,32 @@ def expected_check_run(raw: dict[str, Any]) -> dict[str, Any]:
         "expected_data": [expected_check_run(CHECK_RUN_RAW)],
         "next_cursor": "4",
     },
+    {
+        "name": "list_check_runs_for_ref",
+        "kwargs": {"ref": "abc123"},
+        "path": "/repos/test-org/test-repo/commits/abc123/check-runs",
+        "params": {"filter": "latest"},
+        "pagination": None,
+        "raw": {"total_count": 1, "check_runs": [CHECK_RUN_RAW]},
+        "expected_data": [expected_check_run(CHECK_RUN_RAW)],
+        "next_cursor": "2",
+    },
+    {
+        "name": "list_check_runs_for_ref",
+        "kwargs": {
+            "ref": "abc123",
+            "check_name": "Seer Review",
+            "status": "completed",
+            "timestamp_filter": "all",
+            "pagination": {"cursor": "3", "per_page": 10},
+        },
+        "path": "/repos/test-org/test-repo/commits/abc123/check-runs",
+        "params": {"check_name": "Seer Review", "status": "completed", "filter": "all"},
+        "pagination": {"cursor": "3", "per_page": 10},
+        "raw": {"total_count": 1, "check_runs": [CHECK_RUN_RAW]},
+        "expected_data": [expected_check_run(CHECK_RUN_RAW)],
+        "next_cursor": "4",
+    },
 ]
 
 

tests/unit/test_rpc_integration.py

@@ -694,6 +694,13 @@ def make_client_scm(organization_id, repository_id, server):
         200,
         None,
     ),
+    (
+        "list_check_runs_for_ref",
+        lambda scm: actions.list_check_runs_for_ref(scm, "abc123"),
+        {"total_count": 1, "check_runs": [make_github_check_run()]},
+        200,
+        None,
+    ),
     # Minimize comment (GraphQL)
     (
         "minimize_comment",