github_get_pr_checks

Retrieve check run details for a pull request on GitHub, including status and conclusion, to monitor and verify automated workflows in a specified repository.

Instructions

Get check runs for a pull request

Input Schema

TableJSON Schema

Name	Required	Description	Default
`conclusion`	No
`pr_number`	Yes
`repo_name`	Yes
`repo_owner`	Yes
`status`	No

Implementation Reference

src/mcp_server_git/github/api.py:79-161 (handler)

Main handler function that implements the github_get_pr_checks tool by fetching the PR head SHA, retrieving check runs from GitHub API, optionally filtering by status/conclusion, and formatting a readable output with emojis and details.

async def github_get_pr_checks(
    repo_owner: str,
    repo_name: str,
    pr_number: int,
    status: str | None = None,
    conclusion: str | None = None,
) -> str:
    """Get check runs for a pull request"""
    try:
        async with github_client_context() as client:
            # First get the PR to get the head SHA
            pr_response = await client.get(
                f"/repos/{repo_owner}/{repo_name}/pulls/{pr_number}"
            )
            if pr_response.status != 200:
                return f"❌ Failed to get PR #{pr_number}: {pr_response.status}"

            pr_data = await pr_response.json()
            head_sha = pr_data["head"]["sha"]

            # Get check runs for the head commit
            params = {}
            if status:
                params["status"] = status

            checks_response = await client.get(
                f"/repos/{repo_owner}/{repo_name}/commits/{head_sha}/check-runs",
                params=params,
            )
            if checks_response.status != 200:
                return f"❌ Failed to get check runs: {checks_response.status}"

            checks_data = await checks_response.json()

            # Filter by conclusion if specified
            check_runs = checks_data.get("check_runs", [])
            if conclusion:
                check_runs = [
                    run for run in check_runs if run.get("conclusion") == conclusion
                ]

            # Format the output
            if not check_runs:
                return f"No check runs found for PR #{pr_number}"

            output = [f"Check runs for PR #{pr_number} (commit {head_sha[:8]}):\n"]

            for run in check_runs:
                status_emoji = {
                    "completed": "✅" if run.get("conclusion") == "success" else "❌",
                    "in_progress": "🔄",
                    "queued": "⏳",
                }.get(run["status"], "❓")

                output.append(f"{status_emoji} {run['name']}")
                output.append(f"   Status: {run['status']}")
                if run.get("conclusion"):
                    output.append(f"   Conclusion: {run['conclusion']}")
                output.append(f"   Started: {run.get('started_at', 'N/A')}")
                if run.get("completed_at"):
                    output.append(f"   Completed: {run['completed_at']}")
                if run.get("html_url"):
                    output.append(f"   URL: {run['html_url']}")
                output.append("")

            return "\n".join(output)

    except ValueError as auth_error:
        # Handle authentication/configuration errors specifically
        logger.error(f"Authentication error getting PR checks: {auth_error}")
        return f"❌ {str(auth_error)}"
    except ConnectionError as conn_error:
        # Handle network connectivity issues
        logger.error(f"Connection error getting PR checks: {conn_error}")
        return f"❌ Network connection failed: {str(conn_error)}"
    except Exception as e:
        # Log unexpected errors with full context for debugging
        logger.error(
            f"Unexpected error getting PR checks for PR #{pr_number}: {e}",
            exc_info=True,
        )
        return f"❌ Error getting PR checks: {str(e)}"

src/mcp_server_git/github/models.py:6-12 (schema)
Pydantic model defining the input schema for the github_get_pr_checks tool, including required repo details, PR number, and optional filters for status and conclusion.
```
class GitHubGetPRChecks(BaseModel):
    repo_owner: str
    repo_name: str
    pr_number: int
    status: str | None = None
    conclusion: str | None = None
```

src/mcp_server_git/core/tools.py:338-346 (registration)

ToolDefinition registration in the central tool registry, specifying name, category, description, schema, placeholder handler, and requirements (no repo needed, requires GitHub token).

ToolDefinition(
    name=GitTools.GITHUB_GET_PR_CHECKS,
    category=ToolCategory.GITHUB,
    description="Get check runs for a pull request",
    schema=GitHubGetPRChecks,
    handler=placeholder_handler,
    requires_repo=False,
    requires_github_token=True,
),

src/mcp_server_git/core/handlers.py:194-196 (registration)
Handler wrapper creation and registration in the GitToolRouter, binding the actual github_get_pr_checks function from github.api with expected argument order and error handling decorators.
```
"github_get_pr_checks": self._create_github_handler(
    github_get_pr_checks,
    ["repo_owner", "repo_name", "pr_number", "status", "conclusion"],
```

MCP Git Server