mcp-github-crunchtools 1.4.0__tar.gz → 1.5.0__tar.gz

{mcp_github_crunchtools-1.4.0 → mcp_github_crunchtools-1.5.0}/CHANGELOG.md

@@ -6,6 +6,24 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-10-20
+
+### Added
+
+- `merge_pull_request_tool` and `get_pull_request_checks_tool` work with a
+  fine-grained token. GitHub cannot grant one the Checks permission, so
+  check-runs answers 403; the tools then read the head commit's Actions jobs
+  (Actions: read), each of which is a check run with the same id and name.
+  Only Actions-reported checks are visible that way, so the merge gate
+  refuses a required check that names another app, or that accepts any app
+  and has no commit status. Both results carry `checks_source`.
+
+### Fixed
+
+- `get_pull_request_checks_tool` reads every page of check runs, not just the
+  first, up to the merge gate's page limit; past it the verdict says
+  `truncated` and is not `ready_to_merge`.
+
 ## [1.4.0] - 2026-10-17
 
 ### Added

{mcp_github_crunchtools-1.4.0 → mcp_github_crunchtools-1.5.0}/Containerfile

@@ -27,7 +27,7 @@ FROM quay.io/hummingbird/python:latest
 
 # Labels for container metadata
 LABEL name="mcp-github-crunchtools" \
-      version="1.4.0" \
+      version="1.5.0" \
       summary="Secure MCP server for GitHub issues, pull requests, Actions, releases, files, and search" \
       description="A security-focused MCP server for GitHub built on Red Hat UBI" \
       maintainer="crunchtools.com" \

{mcp_github_crunchtools-1.4.0 → mcp_github_crunchtools-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mcp-github-crunchtools
-Version: 1.4.0
+Version: 1.5.0
 Summary: Secure MCP server for GitHub issues, pull requests, Actions, releases, files, and search
 Author: crunchtools.com
 License-Expression: AGPL-3.0-or-later
@@ -82,12 +82,12 @@ permission the tool needs (see [Token permissions](#token-permissions)).
 | `list_pull_requests_tool` | List pull requests for a repository | Pull requests: read |
 | `get_pull_request_tool` | Get a single pull request by number | Pull requests: read |
 | `get_pull_request_diff_tool` | Get the unified diff for a pull request | Pull requests: read |
-| `get_pull_request_checks_tool` | CI verdict from check-runs and commit statuses; skipped is not failed | Pull requests: read, Commit statuses: read (and see the note under Token permissions) |
+| `get_pull_request_checks_tool` | CI verdict from check-runs and commit statuses; skipped is not failed | Pull requests: read, Commit statuses: read, Actions: read (and see the note under Token permissions) |
 | `list_pull_request_comments_tool` | Conversation comments, diff comments and reviews in one list, each tagged with its kind | Pull requests: read |
 | `create_pull_request_tool` | Open a pull request, optionally as a draft (*write*) | Pull requests: write |
 | `update_pull_request_tool` | Edit, close or reopen a pull request; does not merge (*write*) | Pull requests: write |
 | `reply_to_review_comment_tool` | Reply in the thread of a diff comment (*write*) | Pull requests: write |
-| `merge_pull_request_tool` | Merge, squash or rebase a pull request, only once the base branch's required checks are green on its head (see [The merge gate](#the-merge-gate)) (*write*) | Contents: write; Pull requests and Commit statuses: read |
+| `merge_pull_request_tool` | Merge, squash or rebase a pull request, only once the base branch's required checks are green on its head (see [The merge gate](#the-merge-gate)) (*write*) | Contents: write; Pull requests, Commit statuses and Actions: read |
 
 ### Actions (6 tools)
 
@@ -224,14 +224,23 @@ For a fine-grained personal access token, the repository permissions are:
 | Contents | `get_file_content_tool`, `list_repo_tree_tool` | `merge_pull_request_tool`, `create_release_tool` |
 | Issues | `list_issues_tool`, `get_issue_tool`, `list_issue_comments_tool` | `create_issue_tool`, `update_issue_tool`, `create_issue_comment_tool` |
 | Pull requests | `merge_pull_request_tool`, `list_pull_requests_tool`, `get_pull_request_tool`, `get_pull_request_diff_tool`, `get_pull_request_checks_tool`, `list_pull_request_comments_tool` | `create_pull_request_tool`, `update_pull_request_tool`, `reply_to_review_comment_tool`, `create_issue_comment_tool` on a PR |
-| Actions | `list_workflow_runs_tool`, `get_workflow_run_tool`, `get_failed_job_logs_tool` | `trigger_workflow_tool`, `rerun_workflow_run_tool`, `rerun_failed_jobs_tool` |
+| Actions | `list_workflow_runs_tool`, `get_workflow_run_tool`, `get_failed_job_logs_tool`, `get_pull_request_checks_tool`, `merge_pull_request_tool` | `trigger_workflow_tool`, `rerun_workflow_run_tool`, `rerun_failed_jobs_tool` |
 | Commit statuses | `get_pull_request_checks_tool`, `merge_pull_request_tool` | — |
 
-`get_pull_request_checks_tool` and `merge_pull_request_tool` read check-runs, and GitHub's permission table
-for fine-grained tokens lists no permission for that endpoint. It is readable
-on public repositories; on a private repository use a classic token or a
-GitHub App token. The search tools likewise have no permission of their own:
-they return what the token can already read.
+`get_pull_request_checks_tool` and `merge_pull_request_tool` read check-runs,
+and GitHub's permission table for fine-grained tokens has no permission for
+that endpoint: a fine-grained token gets 403 on a private repository. Both
+tools then read the head commit's GitHub Actions jobs instead (Actions: read).
+Every Actions job is a check run with the same id and name, so the verdict
+and the merge gate are the same for checks GitHub Actions reports. Checks from
+any other app are not visible that way, so the merge gate refuses a required
+check that names another app, or that accepts any app and has no commit
+status, as missing. `checks_source` in each result says which was read, and
+the checks verdict then carries a `note` saying other apps' checks are not
+visible. Only the newest run of each workflow and event is read, and a commit
+with runs of more than 30 workflows is not judged.
+
+The search tools have no permission of their own: they return what the token can already read.
 
 Three things worth knowing before granting write:
 
@@ -266,7 +275,8 @@ merges it:
 4. requires, for every required check on the head commit, a completed check
    run of that name concluding `success`, `skipped` or `neutral` (the most
    recent run of the name decides), or a commit status of `success`. A rule
-   that names an app accepts only that app's check runs. A missing, pending
+   that names an app accepts only that app's check runs. A token that cannot
+   read check-runs is judged on the Actions jobs (see above). A missing, pending
    or failed check refuses the merge, and the error lists each one and why;
 5. reads the pull request again and refuses if its head or base changed
    meanwhile (GitHub's merge call pins the head but not the base), then

{mcp_github_crunchtools-1.4.0 → mcp_github_crunchtools-1.5.0}/README.md

@@ -56,12 +56,12 @@ permission the tool needs (see [Token permissions](#token-permissions)).
 | `list_pull_requests_tool` | List pull requests for a repository | Pull requests: read |
 | `get_pull_request_tool` | Get a single pull request by number | Pull requests: read |
 | `get_pull_request_diff_tool` | Get the unified diff for a pull request | Pull requests: read |
-| `get_pull_request_checks_tool` | CI verdict from check-runs and commit statuses; skipped is not failed | Pull requests: read, Commit statuses: read (and see the note under Token permissions) |
+| `get_pull_request_checks_tool` | CI verdict from check-runs and commit statuses; skipped is not failed | Pull requests: read, Commit statuses: read, Actions: read (and see the note under Token permissions) |
 | `list_pull_request_comments_tool` | Conversation comments, diff comments and reviews in one list, each tagged with its kind | Pull requests: read |
 | `create_pull_request_tool` | Open a pull request, optionally as a draft (*write*) | Pull requests: write |
 | `update_pull_request_tool` | Edit, close or reopen a pull request; does not merge (*write*) | Pull requests: write |
 | `reply_to_review_comment_tool` | Reply in the thread of a diff comment (*write*) | Pull requests: write |
-| `merge_pull_request_tool` | Merge, squash or rebase a pull request, only once the base branch's required checks are green on its head (see [The merge gate](#the-merge-gate)) (*write*) | Contents: write; Pull requests and Commit statuses: read |
+| `merge_pull_request_tool` | Merge, squash or rebase a pull request, only once the base branch's required checks are green on its head (see [The merge gate](#the-merge-gate)) (*write*) | Contents: write; Pull requests, Commit statuses and Actions: read |
 
 ### Actions (6 tools)
 
@@ -198,14 +198,23 @@ For a fine-grained personal access token, the repository permissions are:
 | Contents | `get_file_content_tool`, `list_repo_tree_tool` | `merge_pull_request_tool`, `create_release_tool` |
 | Issues | `list_issues_tool`, `get_issue_tool`, `list_issue_comments_tool` | `create_issue_tool`, `update_issue_tool`, `create_issue_comment_tool` |
 | Pull requests | `merge_pull_request_tool`, `list_pull_requests_tool`, `get_pull_request_tool`, `get_pull_request_diff_tool`, `get_pull_request_checks_tool`, `list_pull_request_comments_tool` | `create_pull_request_tool`, `update_pull_request_tool`, `reply_to_review_comment_tool`, `create_issue_comment_tool` on a PR |
-| Actions | `list_workflow_runs_tool`, `get_workflow_run_tool`, `get_failed_job_logs_tool` | `trigger_workflow_tool`, `rerun_workflow_run_tool`, `rerun_failed_jobs_tool` |
+| Actions | `list_workflow_runs_tool`, `get_workflow_run_tool`, `get_failed_job_logs_tool`, `get_pull_request_checks_tool`, `merge_pull_request_tool` | `trigger_workflow_tool`, `rerun_workflow_run_tool`, `rerun_failed_jobs_tool` |
 | Commit statuses | `get_pull_request_checks_tool`, `merge_pull_request_tool` | — |
 
-`get_pull_request_checks_tool` and `merge_pull_request_tool` read check-runs, and GitHub's permission table
-for fine-grained tokens lists no permission for that endpoint. It is readable
-on public repositories; on a private repository use a classic token or a
-GitHub App token. The search tools likewise have no permission of their own:
-they return what the token can already read.
+`get_pull_request_checks_tool` and `merge_pull_request_tool` read check-runs,
+and GitHub's permission table for fine-grained tokens has no permission for
+that endpoint: a fine-grained token gets 403 on a private repository. Both
+tools then read the head commit's GitHub Actions jobs instead (Actions: read).
+Every Actions job is a check run with the same id and name, so the verdict
+and the merge gate are the same for checks GitHub Actions reports. Checks from
+any other app are not visible that way, so the merge gate refuses a required
+check that names another app, or that accepts any app and has no commit
+status, as missing. `checks_source` in each result says which was read, and
+the checks verdict then carries a `note` saying other apps' checks are not
+visible. Only the newest run of each workflow and event is read, and a commit
+with runs of more than 30 workflows is not judged.
+
+The search tools have no permission of their own: they return what the token can already read.
 
 Three things worth knowing before granting write:
 
@@ -240,7 +249,8 @@ merges it:
 4. requires, for every required check on the head commit, a completed check
    run of that name concluding `success`, `skipped` or `neutral` (the most
    recent run of the name decides), or a commit status of `success`. A rule
-   that names an app accepts only that app's check runs. A missing, pending
+   that names an app accepts only that app's check runs. A token that cannot
+   read check-runs is judged on the Actions jobs (see above). A missing, pending
    or failed check refuses the merge, and the error lists each one and why;
 5. reads the pull request again and refuses if its head or base changed
    meanwhile (GitHub's merge call pins the head but not the base), then

{mcp_github_crunchtools-1.4.0 → mcp_github_crunchtools-1.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mcp-github-crunchtools"
-version = "1.4.0"
+version = "1.5.0"
 description = "Secure MCP server for GitHub issues, pull requests, Actions, releases, files, and search"
 requires-python = ">=3.10"
 license = "AGPL-3.0-or-later"

{mcp_github_crunchtools-1.4.0 → mcp_github_crunchtools-1.5.0}/server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/crunchtools/mcp-github",
     "source": "github"
   },
-  "version": "1.4.0",
+  "version": "1.5.0",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "mcp-github-crunchtools",
-      "version": "1.4.0",
+      "version": "1.5.0",
       "transport": {
         "type": "stdio"
       }

{mcp_github_crunchtools-1.4.0 → mcp_github_crunchtools-1.5.0}/src/mcp_github_crunchtools/__init__.py

@@ -29,7 +29,7 @@ import argparse
 
 from .server import mcp
 
-__version__ = "1.4.0"
+__version__ = "1.5.0"
 __all__ = ["main", "mcp"]
 
 

{mcp_github_crunchtools-1.4.0 → mcp_github_crunchtools-1.5.0}/src/mcp_github_crunchtools/errors.py

@@ -44,6 +44,7 @@ class GitHubApiError(UserError):
 
     def __init__(self, code: int, message: str) -> None:
         super().__init__(f"GitHub API error {code}: {scrub_tokens(message)}")
+        self.status_code = code
 
 
 class NotFoundError(UserError):

{mcp_github_crunchtools-1.4.0 → mcp_github_crunchtools-1.5.0}/src/mcp_github_crunchtools/server.py

@@ -46,7 +46,7 @@ READ_ONLY = {"readOnlyHint": True}
 
 mcp = FastMCP(
     name="mcp-github",
-    version="1.4.0",
+    version="1.5.0",
     instructions=(
         "Secure MCP server for GitHub repositories: issues, pull requests "
         "(open, review discussion, diffs, CI checks, merge), Actions runs and "
@@ -305,7 +305,9 @@ async def get_pull_request_checks_tool(
     failing, pending, or skipped. SKIPPED checks are NOT failures. Use the
     returned ``ready_to_merge`` boolean as the signal for whether the PR is
     clear to merge (True only when nothing is failing or pending and the PR
-    is not known-unmergeable).
+    is not known-unmergeable). A token that cannot read check-runs (any
+    fine-grained token) gets the Actions jobs instead; ``checks_source`` says
+    which, and only Actions-reported checks are then visible.
 
     Args:
         repo: Repository name
@@ -407,7 +409,9 @@ async def merge_pull_request_tool(
     head; when branch protection cannot be read; and when the base branch
     requires no checks at all, unless ``allow_no_required_checks`` is True.
     Passing check runs conclude success, skipped or neutral. The merge is
-    pinned to the head SHA that was checked.
+    pinned to the head SHA that was checked. A token that cannot read
+    check-runs (any fine-grained token) is judged on the Actions jobs, and a
+    required check not reported by GitHub Actions is refused as missing.
 
     Args:
         repo: Repository name

{mcp_github_crunchtools-1.4.0 → mcp_github_crunchtools-1.5.0}/src/mcp_github_crunchtools/tools/pull_requests.py

@@ -4,6 +4,8 @@ Tools for listing, fetching, diffing, checking, opening, merging, and
 discussing GitHub pull requests.
 """
 
+import asyncio
+from collections.abc import Callable
 from typing import Any
 from urllib.parse import quote
 
@@ -30,6 +32,7 @@ from ..models import (
     validate_positive_int,
     validate_ref,
 )
+from .actions import MAX_RUN_JOBS
 
 DIFF_ACCEPT = "application/vnd.github.diff"
 
@@ -45,6 +48,26 @@ MERGE_GATE_MAX_PAGES = 10
 # Check-run conclusions that satisfy a required check.
 PASSING_CONCLUSIONS = frozenset({"success", "skipped", "neutral"})
 
+# The GitHub Actions app. Every Actions job is a check run reported by it,
+# with the job's id and name.
+ACTIONS_APP_ID = 15368
+
+# Where the head commit's check runs were read from. A fine-grained token
+# cannot be granted Checks, so the check-runs endpoint answers it 403; the
+# Actions API (Actions: read) then stands in, seeing only Actions jobs.
+# How many workflow runs' jobs the Actions fallback reads at once, and how
+# many runs (one per workflow and event) it reads at all.
+ACTIONS_JOB_READS_AT_ONCE = 4
+ACTIONS_MAX_RUNS = 30
+
+SOURCE_CHECK_RUNS = "check-runs"
+SOURCE_ACTIONS = "actions"
+ACTIONS_SOURCE_NOTE = (
+    "Check runs were read from the Actions API because this token cannot read "
+    "check-runs (a fine-grained token cannot be granted Checks). Checks "
+    "reported by apps other than GitHub Actions are not visible."
+)
+
 # A required check: its context (check-run name or status context) and, when
 # the rule names one, the id of the GitHub App that must report it.
 RequiredCheck = tuple[str, int | None]
@@ -224,10 +247,11 @@ async def get_pull_request_checks(
     if not sha:
         raise ValidationError("Could not resolve pull request head SHA")
 
-    check_runs = await client.get(f"/repos/{owner}/{repo}/commits/{sha}/check-runs")
+    truncated: list[str] = []
+    check_runs, source = await _head_check_runs(client, owner, repo, sha, truncated.append)
     combined_status = await client.get(f"/repos/{owner}/{repo}/commits/{sha}/status")
 
-    buckets = _classify_checks(check_runs, combined_status)
+    buckets = _classify_checks({"check_runs": check_runs}, combined_status)
     failing = buckets["failing"]
     pending = buckets["pending"]
     skipped = buckets["skipped"]
@@ -236,12 +260,13 @@ async def get_pull_request_checks(
     mergeable = pr.get("mergeable")
     ready_to_merge = not failing and not pending and mergeable is not False
 
-    return {
+    verdict: dict[str, Any] = {
         "pull_number": pull_number,
         "head_sha": sha,
         "mergeable": mergeable,
         "mergeable_state": pr.get("mergeable_state", ""),
         "ready_to_merge": ready_to_merge,
+        "checks_source": source,
         "summary": {
             "passed": len(passed),
             "failing": len(failing),
@@ -253,6 +278,13 @@ async def get_pull_request_checks(
         "skipped": skipped,
         "passed": passed,
     }
+    if source == SOURCE_ACTIONS:
+        verdict["note"] = ACTIONS_SOURCE_NOTE
+    if truncated:
+        # A cut list cannot clear the PR: an unread page may hold a failure.
+        verdict["ready_to_merge"] = False
+        verdict["truncated"] = "Not everything was read of: " + ", ".join(truncated)
+    return verdict
 
 
 async def update_pull_request(
@@ -357,19 +389,39 @@ async def create_pull_request(
     }
 
 
-async def _read_all(client: GitHubClient, path: str, key: str | None) -> list[dict[str, Any]]:
-    """Read every page of a list for the merge gate, or refuse.
+# Called with the path of a list that holds more than was read.
+OnCut = Callable[[str], None]
+
+API_ERRORS = (GitHubApiError, NotFoundError, PermissionDeniedError, RateLimitError)
+
+
+def _refuse_cut(path: str) -> None:
+    """The merge gate does not judge a list it could not read in full."""
+    raise MergeRefusedError(
+        f"Refusing to merge: {path} lists more than the gate reads; "
+        "the checks cannot be judged in full"
+    )
+
+
+async def _read_pages(
+    client: GitHubClient,
+    path: str,
+    key: str | None,
+    on_cut: OnCut,
+    params: dict[str, Any] | None = None,
+    max_pages: int | None = None,
+) -> list[dict[str, Any]]:
+    """Read up to ``max_pages`` (default MERGE_GATE_MAX_PAGES) pages of a
+    list, calling ``on_cut`` if there were more; API errors propagate.
 
     ``key`` names the list inside an object response (``check_runs``,
-    ``statuses``), whose length is known from ``total_count``; None means
-    the response is a bare list, paged by its Link header.
+    ``statuses``, ``jobs``), whose length is known from ``total_count``; None
+    means the response is a bare list, paged by its Link header.
     """
     collected: list[dict[str, Any]] = []
-    for page in range(1, MERGE_GATE_MAX_PAGES + 1):
-        try:
-            result = await client.get(path, params={"per_page": MAX_PER_PAGE, "page": page})
-        except (GitHubApiError, NotFoundError, PermissionDeniedError, RateLimitError) as e:
-            raise MergeRefusedError(f"Refusing to merge: could not read {path}: {e}") from e
+    for page in range(1, (max_pages or MERGE_GATE_MAX_PAGES) + 1):
+        query = {**(params or {}), "per_page": MAX_PER_PAGE, "page": page}
+        result = await client.get(path, params=query)
         if key is None:
             items = result.get("items") or []
             more = "next_page" in result.get("pagination", {})
@@ -379,10 +431,86 @@ async def _read_all(client: GitHubClient, path: str, key: str | None) -> list[di
         collected.extend(item for item in items if isinstance(item, dict))
         if not more:
             return collected
-    raise MergeRefusedError(
-        f"Refusing to merge: {path} has more than {MERGE_GATE_MAX_PAGES} pages; "
-        "the checks cannot be judged in full"
+    on_cut(path)
+    return collected
+
+
+async def _read_all(client: GitHubClient, path: str, key: str | None) -> list[dict[str, Any]]:
+    """Read every page of a list for the merge gate, or refuse."""
+    try:
+        return await _read_pages(client, path, key, _refuse_cut)
+    except API_ERRORS as e:
+        raise MergeRefusedError(f"Refusing to merge: could not read {path}: {e}") from e
+
+
+def _job_as_run(job: dict[str, Any]) -> dict[str, Any]:
+    """An Actions job in the shape of the check run it is."""
+    return {
+        "id": job.get("id"),
+        "name": job.get("name"),
+        "status": job.get("status"),
+        "conclusion": job.get("conclusion"),
+        "html_url": job.get("html_url"),
+        "app": {"id": ACTIONS_APP_ID},
+    }
+
+
+async def _actions_check_runs(
+    client: GitHubClient, owner: str, repo: str, sha: str, on_cut: OnCut
+) -> list[dict[str, Any]]:
+    """The head commit's Actions jobs, as check runs.
+
+    Only the newest run of each workflow and event is read: an older run's
+    job is superseded by the newer run's job of the same name, and a job only
+    the older run had is then missing, which refuses rather than passes. Each
+    run lists the jobs of its latest attempt, up to MAX_RUN_JOBS, read
+    ACTIONS_JOB_READS_AT_ONCE runs at a time. Past ACTIONS_MAX_RUNS runs, only
+    the newest are read and ``on_cut`` is called.
+    """
+    runs_path = f"/repos/{owner}/{repo}/actions/runs"
+    workflow_runs = await _read_pages(
+        client, runs_path, "workflow_runs", on_cut, params={"head_sha": sha}
     )
+    newest: dict[tuple[Any, Any], int] = {}
+    for workflow_run in workflow_runs:
+        run_id = workflow_run.get("id")
+        key = (workflow_run.get("workflow_id"), workflow_run.get("event"))
+        if isinstance(run_id, int) and run_id > newest.get(key, 0):
+            newest[key] = run_id
+    run_ids = sorted(newest.values())
+    if len(run_ids) > ACTIONS_MAX_RUNS:
+        on_cut(runs_path)
+        run_ids = run_ids[-ACTIONS_MAX_RUNS:]
+    gate = asyncio.Semaphore(ACTIONS_JOB_READS_AT_ONCE)
+
+    async def run_jobs(run_id: int) -> list[dict[str, Any]]:
+        async with gate:
+            jobs_path = f"{runs_path}/{run_id}/jobs"
+            pages = MAX_RUN_JOBS // MAX_PER_PAGE
+            return await _read_pages(client, jobs_path, "jobs", on_cut, max_pages=pages)
+
+    per_run = await asyncio.gather(*(run_jobs(run_id) for run_id in run_ids))
+    return [_job_as_run(job) for jobs in per_run for job in jobs if job.get("head_sha") == sha]
+
+
+async def _head_check_runs(
+    client: GitHubClient, owner: str, repo: str, sha: str, on_cut: OnCut
+) -> tuple[list[dict[str, Any]], str]:
+    """The head commit's check runs and where they were read from.
+
+    A token that may not read check-runs (any fine-grained token) gets 403
+    and the Actions jobs instead; any other error propagates. The client
+    maps a rate-limit 403 to RateLimitError and a 401 (a token GitHub
+    rejects outright) to PermissionDeniedError, so a GitHubApiError 403 is a
+    permission refusal.
+    """
+    path = f"/repos/{owner}/{repo}/commits/{sha}/check-runs"
+    try:
+        return await _read_pages(client, path, "check_runs", on_cut), SOURCE_CHECK_RUNS
+    except GitHubApiError as e:
+        if e.status_code != 403:
+            raise
+    return await _actions_check_runs(client, owner, repo, sha, on_cut), SOURCE_ACTIONS
 
 
 def _app_id(value: object) -> int | None:
@@ -463,16 +591,24 @@ def _judge_run(run: dict[str, Any]) -> str | None:
     return None
 
 
-def _index_runs(check_runs: list[dict[str, Any]]) -> dict[RequiredCheck, dict[str, Any]]:
-    """The most recent (highest id) check run per (name, app id) and per
-    (name, None), the latter for checks any app may report."""
+def _index_runs(
+    check_runs: list[dict[str, Any]], any_app: bool = True
+) -> dict[RequiredCheck, dict[str, Any]]:
+    """The most recent (highest id) check run per (name, app id) and, when
+    ``any_app``, per (name, None) for checks any app may report.
+
+    Without ``any_app`` (the runs are only the Actions jobs, so another app's
+    run of the same name may be unseen) a check any app may report is judged
+    by its commit status alone, or is missing.
+    """
     index: dict[RequiredCheck, dict[str, Any]] = {}
     for run in sorted(check_runs, key=lambda r: r.get("id") or 0):
         name = run.get("name")
         if not isinstance(name, str):
             continue
         app_id = (run.get("app") or {}).get("id")
-        index[(name, None)] = run
+        if any_app:
+            index[(name, None)] = run
         if isinstance(app_id, int):
             index[(name, app_id)] = run
     return index
@@ -514,11 +650,15 @@ async def _gate_problems(
     repo: str,
     head_sha: str,
     required: set[RequiredCheck],
-) -> list[str]:
-    """One line per required check that the head commit does not satisfy."""
-    check_runs = await _read_all(
-        client, f"/repos/{owner}/{repo}/commits/{head_sha}/check-runs", "check_runs"
-    )
+) -> tuple[list[str], str]:
+    """One line per required check that the head commit does not satisfy,
+    and where the check runs were read from."""
+    try:
+        check_runs, source = await _head_check_runs(client, owner, repo, head_sha, _refuse_cut)
+    except API_ERRORS as e:
+        raise MergeRefusedError(
+            f"Refusing to merge: could not read the check runs of {head_sha}: {e}"
+        ) from e
     raw_statuses = await _read_all(
         client, f"/repos/{owner}/{repo}/commits/{head_sha}/status", "statuses"
     )
@@ -529,13 +669,13 @@ async def _gate_problems(
         if isinstance(status.get("context"), str):
             statuses[status["context"]] = status
 
-    runs = _index_runs(check_runs)
+    runs = _index_runs(check_runs, any_app=source == SOURCE_CHECK_RUNS)
     problems = []
     for check in sorted(required, key=lambda c: (c[0], c[1] or 0)):
         reason = _judge_check(check, runs, statuses)
         if reason:
             problems.append(f"{check[0]}: {reason}")
-    return problems
+    return problems, source
 
 
 async def _head_and_base(
@@ -617,11 +757,17 @@ async def merge_pull_request(
             f"Refusing to merge: branch {base!r} requires no status checks. "
             "Pass allow_no_required_checks=True to merge without any."
         )
+    source: str | None = None
     if required:
-        problems = await _gate_problems(client, owner, repo, head_sha, required)
+        problems, source = await _gate_problems(client, owner, repo, head_sha, required)
         if problems:
+            via = (
+                " (check runs read from the Actions API; this token cannot read check-runs)"
+                if source == SOURCE_ACTIONS
+                else ""
+            )
             raise MergeRefusedError(
-                f"Refusing to merge: required checks are not green on {head_sha}: "
+                f"Refusing to merge: required checks are not green on {head_sha}{via}: "
                 + "; ".join(problems)
             )
 
@@ -643,6 +789,7 @@ async def merge_pull_request(
         "message": result.get("message"),
         "head_sha": head_sha,
         "required_checks": sorted({context for context, _ in required}),
+        "checks_source": source,
     }
 
 

{mcp_github_crunchtools-1.4.0 → mcp_github_crunchtools-1.5.0}/tests/test_merge_gate.py

@@ -38,6 +38,27 @@ def run(
     }
 
 
+def job(
+    name: str,
+    conclusion: str | None = "success",
+    status: str = "completed",
+    job_id: int = 1,
+    head_sha: str = HEAD,
+) -> dict[str, Any]:
+    """An Actions job as GitHub returns it; its id is its check run's id."""
+    return {
+        "id": job_id,
+        "name": name,
+        "status": status,
+        "conclusion": conclusion,
+        "head_sha": head_sha,
+        "html_url": f"https://github.com/o/r/actions/runs/1/job/{job_id}",
+    }
+
+
+DENIED = (403, "Resource not accessible by personal access token")
+
+
 def ruleset(*contexts: str | tuple[str, int]) -> dict[str, Any]:
     """A required_status_checks rule; a tuple names the integration too."""
     checks = []
@@ -71,13 +92,19 @@ class MockGitHub:
         statuses: list[dict[str, Any]] | None = None,
         page_size: int = 100,
         base: str = "main",
-        fail: dict[str, tuple[int, str]] | None = None,
+        fail: dict[str, tuple[Any, ...]] | None = None,
         moved: dict[str, str] | None = None,
+        jobs: dict[int, list[dict[str, Any]]] | None = None,
+        workflow_of: dict[int, int] | None = None,
     ) -> None:
         self.rules = rules or []
         self.classic = classic
         self.check_runs = check_runs or []
         self.statuses = statuses or []
+        # Actions jobs per workflow run id, read when check-runs is denied.
+        self.jobs = jobs or {}
+        # The workflow of each run id; by default each run is its own workflow.
+        self.workflow_of = workflow_of or {}
         self.page_size = page_size
         self.base = base
         self.fail = fail or {}
@@ -93,6 +120,8 @@ class MockGitHub:
             ("classic", "GET", r"/repos/o/r/branches/.+", self._classic),
             ("check_runs", "GET", rf"/repos/o/r/commits/{HEAD}/check-runs", self._check_runs),
             ("statuses", "GET", rf"/repos/o/r/commits/{HEAD}/status", self._statuses),
+            ("workflow_runs", "GET", r"/repos/o/r/actions/runs", self._workflow_runs),
+            ("jobs", "GET", r"/repos/o/r/actions/runs/\d+/jobs", self._jobs),
         ]
 
     def _page(self, request: httpx.Request, items: list[dict[str, Any]]) -> tuple[list[Any], bool]:
@@ -107,7 +136,8 @@ class MockGitHub:
                 failure = self.fail.get(name)
                 if failure is None:
                     return handler(request)
-                return httpx.Response(failure[0], json={"message": failure[1]})
+                headers = failure[2] if len(failure) > 2 else {}
+                return httpx.Response(failure[0], json={"message": failure[1]}, headers=headers)
         return httpx.Response(404, json={"message": f"unexpected {request.url.path}"})
 
     def _merge(self, _request: httpx.Request) -> httpx.Response:
@@ -149,6 +179,20 @@ class MockGitHub:
         body = {"state": "x", "total_count": len(self.statuses), "statuses": items}
         return httpx.Response(200, json=body)
 
+    def _workflow_runs(self, request: httpx.Request) -> httpx.Response:
+        assert request.url.params.get("head_sha") == HEAD
+        runs = [
+            {"id": run_id, "head_sha": HEAD, "workflow_id": self.workflow_of.get(run_id, run_id)}
+            for run_id in self.jobs
+        ]
+        items, _ = self._page(request, runs)
+        return httpx.Response(200, json={"total_count": len(runs), "workflow_runs": items})
+
+    def _jobs(self, request: httpx.Request) -> httpx.Response:
+        jobs = self.jobs[int(request.url.path.split("/")[-2])]
+        items, _ = self._page(request, jobs)
+        return httpx.Response(200, json={"total_count": len(jobs), "jobs": items})
+
     @property
     def merges(self) -> list[httpx.Request]:
         return [r for r in self.requests if r.method == "PUT"]
@@ -194,6 +238,7 @@ class TestMergeGate:
             "message": "Merged",
             "head_sha": HEAD,
             "required_checks": ["Gatehouse triage", "lint", "test"],
+            "checks_source": "check-runs",
         }
         (put,) = github.merges
         assert put.url.path == MERGE_PATH
@@ -493,7 +538,7 @@ class TestMergeGate:
             page_size=2,
         )
 
-        assert "more than 2 pages" in await refused(github)
+        assert "lists more than the gate reads" in await refused(github)
 
     async def test_pr_without_head_refused(self) -> None:
         from mcp_github_crunchtools.errors import MergeRefusedError
@@ -542,7 +587,7 @@ class TestMergeGate:
 
     @pytest.mark.parametrize(
         ("route", "code"),
-        [("rules", 403), ("rules", 500), ("check_runs", 403), ("statuses", 500), ("pull", 404)],
+        [("rules", 403), ("rules", 500), ("check_runs", 500), ("statuses", 500), ("pull", 404)],
     )
     async def test_unreadable_gate_data_never_merges(self, route: str, code: int) -> None:
         from mcp_github_crunchtools.errors import UserError
@@ -560,6 +605,245 @@ class TestMergeGate:
         assert github.merges == []
 
 
+class TestFineGrainedToken:
+    """A fine-grained token cannot read check-runs; the Actions jobs stand in."""
+
+    async def test_green_jobs_merge(self) -> None:
+        github = MockGitHub(
+            rules=[ruleset(("test", ACTIONS_APP), ("lint", ACTIONS_APP))],
+            fail={"check_runs": DENIED},
+            jobs={7: [job("test", job_id=11)], 8: [job("lint", job_id=12)]},
+        )
+
+        result = await merge(github)
+
+        assert result["merged"] is True
+        assert result["checks_source"] == "actions"
+        assert github.merges[0].url.path == MERGE_PATH
+
+    @pytest.mark.parametrize(
+        ("conclusion", "status", "reason"),
+        [
+            ("failure", "completed", "failed (check run concluded failure)"),
+            (None, "in_progress", "pending (check run in_progress)"),
+        ],
+    )
+    async def test_red_or_running_job_refused(
+        self, conclusion: str | None, status: str, reason: str
+    ) -> None:
+        github = MockGitHub(
+            rules=[ruleset(("test", ACTIONS_APP))],
+            fail={"check_runs": DENIED},
+            jobs={7: [job("test", conclusion=conclusion, status=status)]},
+        )
+
+        message = await refused(github)
+
+        assert f"test: {reason}" in message
+        assert "read from the Actions API" in message
+
+    async def test_latest_rerun_decides(self) -> None:
+        github = MockGitHub(
+            rules=[ruleset(("test", ACTIONS_APP))],
+            fail={"check_runs": DENIED},
+            jobs={7: [job("test", "failure", job_id=11)], 9: [job("test", job_id=20)]},
+        )
+
+        assert (await merge(github))["merged"] is True
+
+    async def test_older_run_of_same_workflow_not_read(self) -> None:
+        github = MockGitHub(
+            rules=[ruleset(("test", ACTIONS_APP))],
+            fail={"check_runs": DENIED},
+            jobs={7: [job("test", job_id=11)], 9: [job("lint", job_id=20)]},
+            workflow_of={7: 1, 9: 1},
+        )
+
+        assert "test: missing" in await refused(github)
+        assert "/repos/o/r/actions/runs/7/jobs" not in github.paths()
+
+    async def test_too_many_workflows_refused(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        from mcp_github_crunchtools.tools import pull_requests as pr_mod
+
+        monkeypatch.setattr(pr_mod, "ACTIONS_MAX_RUNS", 1)
+        github = MockGitHub(
+            rules=[ruleset(("test", ACTIONS_APP))],
+            fail={"check_runs": DENIED},
+            jobs={7: [job("test")], 8: [job("lint")]},
+        )
+
+        assert "/actions/runs lists more than the gate reads" in await refused(github)
+        assert not any(path.endswith("/jobs") for path in github.paths())
+
+    async def test_any_app_check_not_satisfied_by_a_job(self) -> None:
+        # Another app's run of the same name may be failing, unseen.
+        github = MockGitHub(
+            rules=[ruleset("test")], fail={"check_runs": DENIED}, jobs={7: [job("test")]}
+        )
+
+        assert "test: missing" in await refused(github)
+
+    async def test_any_app_check_still_met_by_status(self) -> None:
+        github = MockGitHub(
+            rules=[ruleset("ci/legacy")],
+            fail={"check_runs": DENIED},
+            statuses=[{"id": 1, "context": "ci/legacy", "state": "success"}],
+        )
+
+        assert (await merge(github))["merged"] is True
+
+    async def test_other_app_check_refused(self) -> None:
+        github = MockGitHub(
+            rules=[ruleset(("test", 999))], fail={"check_runs": DENIED}, jobs={7: [job("test")]}
+        )
+
+        assert "test: missing (no check run from app 999" in await refused(github)
+
+    async def test_job_on_another_commit_ignored(self) -> None:
+        github = MockGitHub(
+            rules=[ruleset(("test", ACTIONS_APP))],
+            fail={"check_runs": DENIED},
+            jobs={7: [job("test", head_sha=OTHER)]},
+        )
+
+        assert "test: missing" in await refused(github)
+
+    @pytest.mark.parametrize("failure", [(500, "boom"), (404, "Not Found")])
+    async def test_other_check_runs_errors_do_not_fall_back(self, failure: tuple[int, str]) -> None:
+        github = MockGitHub(
+            rules=[ruleset(("test", ACTIONS_APP))],
+            fail={"check_runs": failure},
+            jobs={7: [job("test")]},
+        )
+
+        assert "could not read the check runs of" in await refused(github)
+        assert not any("/actions/" in path for path in github.paths())
+
+    async def test_rejected_token_does_not_fall_back(self) -> None:
+        github = MockGitHub(
+            rules=[ruleset(("test", ACTIONS_APP))],
+            fail={"check_runs": (401, "Bad credentials")},
+            jobs={7: [job("test")]},
+        )
+
+        assert "could not read the check runs of" in await refused(github)
+        assert not any("/actions/" in path for path in github.paths())
+
+    async def test_rate_limited_check_runs_do_not_fall_back(self) -> None:
+        limited = (403, "API rate limit exceeded", {"x-ratelimit-remaining": "0"})
+        github = MockGitHub(
+            rules=[ruleset(("test", ACTIONS_APP))],
+            fail={"check_runs": limited},
+            jobs={7: [job("test")]},
+        )
+
+        assert "could not read the check runs of" in await refused(github)
+        assert not any("/actions/" in path for path in github.paths())
+
+    async def test_too_many_jobs_in_a_run_refused(self) -> None:
+        from mcp_github_crunchtools.tools.actions import MAX_RUN_JOBS
+
+        github = MockGitHub(
+            rules=[ruleset(("test", ACTIONS_APP))],
+            fail={"check_runs": DENIED},
+            jobs={7: [job("test", job_id=i) for i in range(1, MAX_RUN_JOBS + 2)]},
+        )
+
+        assert "/actions/runs/7/jobs lists more than the gate reads" in await refused(github)
+
+    async def test_too_many_workflow_run_pages_refused(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        from mcp_github_crunchtools.tools import pull_requests as pr_mod
+
+        monkeypatch.setattr(pr_mod, "MERGE_GATE_MAX_PAGES", 1)
+        github = MockGitHub(
+            rules=[ruleset(("test", ACTIONS_APP))],
+            fail={"check_runs": DENIED},
+            jobs={7: [job("test")], 8: [job("test", job_id=2)]},
+            page_size=1,
+        )
+
+        assert "/actions/runs lists more than the gate reads" in await refused(github)
+
+    async def test_unreadable_jobs_refuse(self) -> None:
+        github = MockGitHub(
+            rules=[ruleset(("test", ACTIONS_APP))],
+            fail={"check_runs": DENIED, "jobs": DENIED},
+            jobs={7: [job("test")]},
+        )
+
+        assert "could not read the check runs of" in await refused(github)
+
+    async def test_checks_tool_reads_jobs(self) -> None:
+        from mcp_github_crunchtools.tools import get_pull_request_checks
+
+        github = MockGitHub(
+            fail={"check_runs": DENIED},
+            jobs={7: [job("test", job_id=11), job("lint", "skipped", job_id=12)]},
+        )
+        with _patch_transport(github):
+            verdict = await get_pull_request_checks(owner="o", repo="r", pull_number=12)
+
+        assert verdict["checks_source"] == "actions"
+        assert "not visible" in verdict["note"]
+        assert verdict["summary"] == {"passed": 1, "failing": 0, "pending": 0, "skipped": 1}
+        assert verdict["ready_to_merge"] is True
+
+    async def test_checks_tool_reads_later_pages(self) -> None:
+        from mcp_github_crunchtools.tools import get_pull_request_checks
+
+        github = MockGitHub(
+            check_runs=[run("a", run_id=1), run("b", conclusion="failure", run_id=2)], page_size=1
+        )
+        with _patch_transport(github):
+            verdict = await get_pull_request_checks(owner="o", repo="r", pull_number=12)
+
+        pages = [r.url.params.get("page") for r in github.requests if "check-runs" in r.url.path]
+        assert pages == ["1", "2"]
+        assert [f["name"] for f in verdict["failing"]] == ["b"]
+        assert verdict["ready_to_merge"] is False
+        assert "truncated" not in verdict
+
+    async def test_checks_tool_flags_truncation(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        from mcp_github_crunchtools.tools import get_pull_request_checks
+        from mcp_github_crunchtools.tools import pull_requests as pr_mod
+
+        monkeypatch.setattr(pr_mod, "MERGE_GATE_MAX_PAGES", 1)
+        github = MockGitHub(check_runs=[run("a", run_id=1), run("b", run_id=2)], page_size=1)
+        with _patch_transport(github):
+            verdict = await get_pull_request_checks(owner="o", repo="r", pull_number=12)
+
+        assert verdict["ready_to_merge"] is False
+        assert "check-runs" in verdict["truncated"]
+
+    async def test_checks_tool_reads_newest_runs_past_the_cap(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        from mcp_github_crunchtools.tools import get_pull_request_checks
+        from mcp_github_crunchtools.tools import pull_requests as pr_mod
+
+        monkeypatch.setattr(pr_mod, "ACTIONS_MAX_RUNS", 1)
+        github = MockGitHub(
+            fail={"check_runs": DENIED},
+            jobs={7: [job("old", job_id=11)], 8: [job("new", job_id=12)]},
+        )
+        with _patch_transport(github):
+            verdict = await get_pull_request_checks(owner="o", repo="r", pull_number=12)
+
+        assert "/repos/o/r/actions/runs/7/jobs" not in github.paths()
+        assert [p["name"] for p in verdict["passed"]] == ["new"]
+        assert "/repos/o/r/actions/runs" in verdict["truncated"]
+        assert verdict["ready_to_merge"] is False
+
+    async def test_no_required_checks_reports_no_source(self) -> None:
+        github = MockGitHub()
+
+        result = await merge(github, allow_no_required_checks=True)
+
+        assert result["checks_source"] is None
+
+
 class TestMergeTool:
     """The registered MCP tool exposes and forwards the gate's argument."""
 

{mcp_github_crunchtools-1.4.0 → mcp_github_crunchtools-1.5.0}/uv.lock

@@ -922,7 +922,7 @@ wheels = [
 
 [[package]]
 name = "mcp-github-crunchtools"
-version = "1.4.0"
+version = "1.5.0"
 source = { editable = "." }
 dependencies = [
     { name = "fastmcp" },