list_pull_requests
List the pull requests komrad has recorded for a repository, open ones first.
read-onlyidempotentMCP toolPull Request
A repository without a live agent may be out of date. list_forge_pull_requests reads the forge directly.
Calling it#
curl -X POST http://127.0.0.1:8787/komrad.pullrequest.v1.PullRequestService/ListPullRequests \
-H 'Content-Type: application/json' \
-d '{
"repository_url": "<repository_url>"
}'komrad rpc list-pull-requests \
--repository-url '<string>'{
"name": "list_pull_requests",
"arguments": {
"repository_url": "<repository_url>"
}
}Offered by the komrad MCP server to writer, orchestrator agents.
Request#
ListPullRequestsRequest#
| Field | Type | Description |
|---|---|---|
repository_url | string* at most 2048 characters | The repository the pull requests merge into, as a git remote or a web address. |
head_branch | string at most 512 characters | The branch the pull requests merge from. Empty lists every pull request komrad has recorded for the repository. |
pagination | Pagination | The page to read. The page size defaults to twenty and is at most a hundred. |
Response#
ListPullRequestsResponse#
| Field | Type | Description |
|---|---|---|
pull_requests | PullRequest[] | One page of pull requests, open ones first, each group newest first. |
next_page_token | string | The cursor for the next page. Unset on the last page. |
Types#
Pagination#
Pagination selects one page of a listing.
PullRequest#
PullRequest is a pull request as komrad last read it from the forge.
| Field | Type | Description |
|---|---|---|
id | uuid* | The pull request's id. |
forge | Kind | The kind of forge the pull request is on. |
provider_id | string | The forge's own stable id for the pull request, such as GitHub's |
url | string | The pull request's web address. |
repository_url | string | The web address of the repository the pull request merges into. |
head_repository_url | string | The web address of the repository the pull request's branch is in. Empty when the forge no longer has that repository. |
number | int32 | The pull request's number, unique within its repository. |
title | string | The pull request's title. |
head_branch | string | The branch the pull request merges from. |
head_sha | string | The commit at the tip of the pull request's branch. |
base_branch | string | The branch the pull request merges into. |
base_sha | string | The commit at the tip of the branch the pull request merges into. |
draft | bool | Whether the pull request is a draft. |
state | PullRequestState | The pull request's state. |
opened_at | timestamp | When the pull request was opened. |
changed_at | timestamp | When the pull request last changed on the forge. |
merged_at | timestamp | When the pull request merged. Unset until the pull request merges. |
closed_at | timestamp | When the pull request closed, merged or not. Unset while the pull request is open. |
merge_readiness | MergeReadiness | How close the forge is to merging the pull request. |
author | string | The login of the pull request's author. Empty when the forge no longer has the account. |
body | string | The pull request's description. Empty when it has none. |
MergeReadiness#
MergeReadiness is how close a pull request's head commit is to merging.
| Field | Type | Description |
|---|---|---|
decision | ReviewDecision | The forge's review decision. |
checks | Checks | The state of the checks on the head commit. Unspecified when the forge last reported on an older head. |
mergeability | Mergeability | The forge's mergeability, or the last value for the same head while the forge recomputes it. |
mergeability_unconfirmed | bool | Whether |
auto_merge | bool | Whether auto-merge is on, so the forge merges once the checks and reviews pass. |
auto_mergeable | bool | Whether the forge would let komrad turn auto-merge on now. The forge refuses for a draft, a pull request with nothing left to wait for, and a repository that does not allow auto-merge. |
credential_approved | bool | Whether komrad's credential has an approval standing on the pull request. |
credential_can_approve | bool | Whether the forge would take an approval from komrad's credential now. The forge refuses one from the pull request's author and from a user it does not let approve. |
reviewers | Reviewer[] | The users who have reviewed the pull request or have a review request waiting, without its author. Empty before the forge has been read. |
Reviewer#
Reviewer is one user who has reviewed a pull request or been asked to.
| Field | Type | Description |
|---|---|---|
login | string | The reviewer's login on the forge. |
verdict | ReviewerVerdict | Where the reviewer's latest review leaves them. |
requested | bool | Whether a review request to the reviewer is waiting. |
Kind#
Kind is the kind of forge a host runs.
PullRequestState#
PullRequestState is the state of a pull request, worked out from the forge's report. A finished state wins over an open one.
| Value | Description |
|---|---|
unread | Komrad has not read the repository yet. |
none | Komrad read the repository and found no pull request from the branch. |
open | Open, without a review decision that decides it. |
approved | Open, and the forge would merge it now. |
changes_requested | Open, with a reviewer asking for changes. |
draft | A draft, whatever its reviews say. |
merged | Merged. |
closed | Closed without merging. |
failing | Open, with a failing check on the head commit, whatever its reviews say. |
approved_waiting | Approved, but behind its base branch or blocked by a branch rule. |
conflicting | Open, and in conflict with its base branch, whatever its reviews say. |
checks_running | Open, with checks running on the head commit and no reviewer asking for changes. |
rereview_requested | Open, and every reviewer who asked for changes has been asked to review again. |
ReviewDecision#
ReviewDecision is the forge's decision on a pull request's reviews.
| Value | Description |
|---|---|
none | The forge reports no decision. |
pending | A required review has not been given. |
approved | The forge counts the pull request as approved. |
changes_requested | A reviewer is asking for changes. |
rereview_requested | Every reviewer who asked for changes has been asked to review again. |
Checks#
Checks is the overall state of the checks on a pull request's head commit.
| Value | Description |
|---|---|
none | The head commit has no checks. |
pending | Checks are still running. |
passing | Every check passed. |
failing | At least one check failed, and every check has finished. |
failing_running | At least one check failed, and others are still running. |
Mergeability#
Mergeability is whether the forge would merge a pull request, given its base branch and branch rules.
| Value | Description |
|---|---|
unknown | The forge has not worked it out yet. |
clean | The forge would merge the pull request now. |
unstable | Some checks are not passing. |
blocked | A branch rule is not met, such as a required review. |
behind | The base branch has commits the pull request's branch does not. |
conflicting | The branch is in conflict with its base branch. |
ReviewerVerdict#
ReviewerVerdict is where one reviewer's latest review of a pull request leaves them.
| Value | Description |
|---|---|
none | The reviewer has not reviewed the pull request. |
approved | The reviewer approved. |
changes_requested | The reviewer asked for changes. |
commented | The reviewer left comments without approving or asking for changes. |
dismissed | The reviewer's latest review was dismissed. |