create_pull_request

@tool_spec(​
spec={​
'name': 'create_pull_request',​
'description': """ Create a new pull request.​
​
This function creates a new pull request in the specified
repository.​
It requires the owner of the repository, the repository name, the
title for the pull request,​
the head branch (the branch with the proposed changes), and the
base branch (the branch​
into which the changes will be merged). Optional parameters
include the body of the​
pull request, whether it should be a draft, and whether
maintainers can modify it.​
The function returns details of the created pull request. """,​
'parameters': {​
'type': 'object',​
'properties': {​
'owner': {​
'type':​
'string',​
'description':​
'The account owner of the repository. The name is not
case sensitive.'​
},​
'repo': {​
'type':​
'string',​
'description':​
'The name of the repository without the .git
extension. The name is not case sensitive.'​
},​
'title': {​
'type': 'string',​
'description': 'The title of the new pull request.'​
},​
'head': {​
'type':​
'string',​
'description':​
'The name of the branch where your changes are
implemented.'​
},​
'base': {​
'type':​
'string',​
 'description':​
'The name of the branch you want the changes pulled
into.'​
},​
'body': {​
'type':​
'string',​
'description':​
'The contents of the pull request. Defaults to None.'​
},​
'draft': {​
'type':​
'boolean',​
'description':​
'Indicates whether the pull request is a draft.
Defaults to False.'​
},​
'maintainer_can_modify': {​
'type':​
'boolean',​
'description':​
""" Indicates whether maintainers can modify the pull
request.​
Defaults to False. """​
}​
},​
'required': ['owner', 'repo', 'title', 'head', 'base']​
}​
})​
def create_pull_request(owner: str,​
repo: str,​
title: str,​
head: str,​
base: str,​
body: Optional[str] = None,​
draft: bool = False,​
maintainer_can_modify: bool = False) -> Dict[str,
Any]

Create a new pull request.

This function creates a new pull request in the specified repository.

It requires the owner of the repository, the repository name, the title for the pull request,

the head branch (the branch with the proposed changes), and the base branch (the branch

into which the changes will be merged). Optional parameters include the body of the

pull request, whether it should be a draft, and whether maintainers can modify it.
The function returns details of the created pull request.

Args:
owner (str): The account owner of the repository. The name is not case sensitive.

repo (str): The name of the repository without the .git extension. The name is not case
sensitive.

title (str): The title of the new pull request.

head (str): The name of the branch where your changes are implemented.

base (str): The name of the branch you want the changes pulled into.

body (Optional[str]): The contents of the pull request. Defaults to None.

draft (bool): Indicates whether the pull request is a draft. Defaults to False.

maintainer_can_modify (bool): Indicates whether maintainers can modify the pull request.

Defaults to False.

Returns:
Dict[str, Any]: A dictionary containing the details of the newly created pull request with the
following keys:

id (int): The unique identifier of the pull request.

number (int): The pull request number, unique within the repository.

title (str): The title of the pull request.

body (Optional[str]): The description or body content of the pull request.

state (str): The current state of the pull request (e.g., 'open').

draft (bool): Indicates if the pull request is a draft.

maintainer_can_modify (bool): Indicates if maintainers are allowed to modify the pull

request.

user (Dict[str, Any]): Details of the user who created the pull request.

login (str): The username of the creator.

id (int): The unique identifier for the user.

type (str): The type of the account (e.g., 'User', 'Bot').

head (Dict[str, Any]): Details of the head branch (the branch with the proposed changes).
label (str): The user-friendly label for the head branch (e.g., 'owner:feature-branch').

ref (str): The reference of the head branch (e.g., 'feature-branch').

sha (str): The commit SHA of the head branch.

repo (Dict[str, Any]): Details of the repository containing the head branch.

id (int): Repository ID.

name (str): Repository name.

full_name (str): Full repository name (e.g., 'owner/repo-name').

private (bool): Whether the repository is private.

owner (Dict[str, Any]): Repository owner details.

login (str): The username of the owner.

id (int): The unique identifier for the owner.

type (str): The type of the account (e.g., 'User', 'Organization').

base (Dict[str, Any]): Details of the base branch (the branch the changes will be merged
into).

label (str): The user-friendly label for the base branch (e.g., 'owner:main').

ref (str): The reference of the base branch (e.g., 'main').

sha (str): The commit SHA of the base branch.

repo (Dict[str, Any]): Details of the repository containing the base branch.

id (int): Repository ID.

name (str): Repository name.

full_name (str): Full repository name (e.g., 'owner/repo-name').

private (bool): Whether the repository is private.

owner (Dict[str, Any]): Repository owner details.

login (str): The username of the owner.

id (int): The unique identifier for the owner.

type (str): The type of the account (e.g., 'User', 'Organization').

created_at (str): Timestamp indicating when the pull request was created (ISO 8601
format).

updated_at (str): Timestamp indicating when the pull request was last updated (ISO 8601
format).

Raises:
NotFoundError: If the repository, head branch, or base branch does not exist.

ValidationError: If required fields (title, head, base) are missing or invalid.

UnprocessableEntityError: If a PR already exists for these branches or if there are no

commits

between head and base.

create_pull_request_review
@tool_spec(​
spec={​
'name': 'create_pull_request_review',​
'description': """ Creates a review on a specified pull request.​
​
This function simulates the GitHub API endpoint for creating a
pull request review.​
It allows for submitting reviews with different states (APPROVE,
REQUEST_CHANGES, COMMENT, PENDING),​
an optional body text, and an array of inline draft review
comments.​
​
The creation of a review with states other than PENDING typically
triggers notifications.​
Pull request reviews created in the PENDING state (when the
`event` parameter is​
left blank or not provided) are not considered "submitted" and
therefore do not​
include the `submitted_at` property in the response until they
are explicitly submitted​
via a separate action (not part of this function). """,​
'parameters': {​
'type': 'object',​
'properties': {​
'owner': {​
'type':​
'string',​
'description':​
'The account owner of the repository. The name is not
case sensitive.'​
},​
'repo': {​
 'type':​
'string',​
'description':​
'The name of the repository without the .git
extension. The name is not case sensitive.'​
},​
'pull_number': {​
'type':​
'integer',​
'description':​
'The number that identifies the pull request within
the repository.'​
},​
'commit_id': {​
'type':​
'string',​
'description':​
""" The SHA of the commit to which the review
applies. Defaults to None.​
If not provided, the review applies to the latest
commit on the pull request's head branch.​
Specifying an older commit SHA might result in
comments being outdated if subsequent​
commits modify the commented lines. """​
},​
'body': {​
'type':​
'string',​
'description':​
""" The main body text of the pull request review.
Defaults to None.​
This field is **required** if the `event` is
'REQUEST_CHANGES' or 'COMMENT'.​
It can be an empty string. """​
},​
'event': {​
'type':​
'string',​
'description':​
""" The review action to perform. Defaults to None.
Valid values are:​
- 'APPROVE': Submits an approving review.​
- 'REQUEST_CHANGES': Submits a review requesting
changes. Requires `body`.​
- 'COMMENT': Submits a general comment review.
Requires `body`.​
If `event` is `None` or an empty string, the review
is created in a 'PENDING' state​
and is not considered submitted. """​
 },​
'comments': {​
'type': 'array',​
'description':​
""" An array of draft review comment objects to be​
included with this review. Defaults to None. Each
comment dictionary in the list should conform to the​
following structure and validations (see
`PullRequestReviewCommentInput` model): """,​
'items': {​
'type': 'object',​
'properties': {​
'path': {​
'type':​
'string',​
'description':​
'Required. The relative path to the file
being commented on.'​
},​
'body': {​
'type':​
'string',​
'description':​
'Required. The text of the review
comment.'​
},​
'position': {​
'type':​
'integer',​
'description':​
""" The line index in the diff hunk to
which the comment applies.​
This is mutually exclusive with `line`
for specifying a single-line comment location;​
one of them must be provided if not a
multi-line comment on the file.​
Must be >= 1. """​
},​
'line': {​
'type':​
'integer',​
'description':​
""" The line number in the file's diff
that the comment applies to.​
For a multi-line comment, this is the
last line of the range.​
This is mutually exclusive with
`position` for single-line comments. Must be >= 1. """​
},​
 'side': {​
'type':​
'string',​
'description':​
""" The side of the diff to which the
comment applies.​
Can be 'LEFT' or 'RIGHT'. Defaults to
'RIGHT' if `line` is provided. Only used for line-level​
comments. """​
},​
'start_line': {​
'type':​
'integer',​
'description':​
""" For a multi-line comment, the first
line of the​
comment's range. Requires `line` to
also be provided. Must be <= `line` and >= 1. """​
},​
'start_side': {​
'type':​
'string',​
'description':​
""" For a multi-line comment, the side of
the diff​
for the `start_line`. Can be 'LEFT' or
'RIGHT'. Defaults to the value of `side`​
if `start_line` is provided and
`start_side` is not. Requires `start_line`. """​
}​
},​
'required': ['path', 'body']​
}​
}​
},​
'required': ['owner', 'repo', 'pull_number']​
}​
})​
def create_pull_request_review(​
owner: str,​
repo: str,​
pull_number: int,​
commit_id: Optional[str] = None,​
body: Optional[str] = None,​
event: Optional[str] = None,​
comments: Optional[List[Dict[str, Union[str,​
int]]]] = None) -> Dict[str,
Any]
Creates a review on a specified pull request.

This function simulates the GitHub API endpoint for creating a pull request review.

It allows for submitting reviews with different states (APPROVE, REQUEST_CHANGES,

COMMENT, PENDING),

an optional body text, and an array of inline draft review comments.

The creation of a review with states other than PENDING typically triggers notifications.

Pull request reviews created in the PENDING state (when the `event` parameter is

left blank or not provided) are not considered "submitted" and therefore do not

include the `submitted_at` property in the response until they are explicitly submitted

via a separate action (not part of this function).

Args:
owner (str): The account owner of the repository. The name is not case sensitive.

repo (str): The name of the repository without the .git extension. The name is not case
sensitive.

pull_number (int): The number that identifies the pull request within the repository.

commit_id (Optional[str]): The SHA of the commit to which the review applies. Defaults to
None.

If not provided, the review applies to the latest commit on the pull request's head branch.

Specifying an older commit SHA might result in comments being outdated if subsequent

commits modify the commented lines.

body (Optional[str]): The main body text of the pull request review. Defaults to None.

This field is **required** if the `event` is 'REQUEST_CHANGES' or 'COMMENT'.

It can be an empty string.

event (Optional[str]): The review action to perform. Defaults to None. Valid values are:

• 'APPROVE': Submits an approving review.

• 'REQUEST_CHANGES': Submits a review requesting changes. Requires

`body`.

• 'COMMENT': Submits a general comment review. Requires `body`.

If `event` is `None` or an empty string, the review is created in a 'PENDING' state

and is not considered submitted.

comments (Optional[List[Dict[str, Union[str, int]]]]): An array of draft review comment

objects to be

included with this review. Defaults to None. Each comment dictionary in the list should
conform to the

following structure and validations (see `PullRequestReviewCommentInput` model):

• path (str): Required. The relative path to the file being commented on.

• body (str): Required. The text of the review comment.

• position (Optional[int]): The line index in the diff hunk to which the
comment applies.

This is mutually exclusive with `line` for specifying a single-line comment location;

one of them must be provided if not a multi-line comment on the file.

Must be >= 1.

• line (Optional[int]): The line number in the file's diff that the comment
applies to.

For a multi-line comment, this is the last line of the range.

This is mutually exclusive with `position` for single-line comments. Must be >= 1.

• side (Optional[str]): The side of the diff to which the comment applies.

Can be 'LEFT' or 'RIGHT'. Defaults to 'RIGHT' if `line` is provided. Only used for line-level

comments.

• start_line (Optional[int]): For a multi-line comment, the first line of the

comment's range. Requires `line` to also be provided. Must be <= `line` and >= 1.

• start_side (Optional[str]): For a multi-line comment, the side of the diff

for the `start_line`. Can be 'LEFT' or 'RIGHT'. Defaults to the value of `side`

if `start_line` is provided and `start_side` is not. Requires `start_line`.

Returns:
Dict[str, Any]: A dictionary representing the created pull request review, structured
according to the `PullRequestReview` Pydantic model. Key fields include:

• id (int): The unique identifier for the review.

• node_id (str): The GraphQL node ID for the review.

• pull_request_id (int): The ID of the pull request to which this review

belongs.

• user (Dict[str, Any]): A simplified representation of the user who created

the review,

containing:

• id (int): The user's unique ID.

• login (str): The user's login name.

• body (Optional[str]): The body text of the review. Will be present, even if
None.

• state (str): The state of the review (e.g., "APPROVED", "PENDING",

"COMMENTED",

"CHANGES_REQUESTED").

• commit_id (str): The SHA of the commit to which this review applies.

• submitted_at (Optional[str]): An ISO 8601 timestamp string (e.g.,

"2023-01-15T10:30:00Z")

indicating when the review was submitted. This field is `None` if the review's

`state` is 'PENDING'.

• author_association (str): Indicates the relationship of the review author to

the

repository (e.g., "OWNER", "MEMBER", "COLLABORATOR", "CONTRIBUTOR", "NONE").

Raises:
NotFoundError: If the specified repository, pull request, or (if provided) `commit_id`

cannot be found. Also raised for non-positive `pull_number`.

ValidationError: If input parameters are invalid (e.g., unknown `event` type, missing

`body` for certain events, malformed `comments` array or objects within it,

invalid `commit_id` format).

ForbiddenError: If the authenticated user does not have permission to create a review

on the pull request (e.g., lacks write access and is not the PR author).

UnprocessableEntityError: If the review cannot be created due to a business logic

violation, such as attempting to review a locked pull request or referencing

a commit that doesn't exist in the repository.

list_repository_pull_requests
@tool_spec(​
spec={​
'name': 'list_repository_pull_requests',​
'description': """ List and filter repository pull requests.​
​
This function lists and filters pull requests for a specified
repository.​
It allows querying for pull requests based on their state (open,
closed, or all).​
Results can be sorted by various criteria such as creation date,​
update date, popularity (number of comments), or by identifying
long-running​
pull requests. The direction of sorting (ascending or descending)
can also be​
specified. Pagination options are available to control the number
of results​
per page and to fetch specific pages of results, facilitating the
handling of​
large datasets. """,​
'parameters': {​
'type': 'object',​
'properties': {​
'owner': {​
'type':​
'string',​
'description':​
'The account owner of the repository. The name is not
case sensitive.'​
},​
'repo': {​
'type':​
'string',​
'description':​
'The name of the repository without the .git
extension. The name is not case sensitive.'​
},​
'state': {​
'type':​
 'string',​
'description':​
"Filter by state. Possible values: 'open', 'closed',
'all'. Default: 'open'."​
},​
'sort': {​
'type':​
'string',​
'description':​
"What to sort results by. 'popularity' will sort by
the number of comments. 'long-running' will sort by date created and will
limit the results to pull requests that have been open for more than a
month and have had activity within the past month. Possible values:
'created', 'updated', 'popularity', 'long-running'. Default: 'created'."​
},​
'direction': {​
'type':​
'string',​
'description':​
"The direction of the sort. Possible values: 'asc',
'desc'. Default: 'desc' when 'sort' is 'created' or not specified,
otherwise 'asc'."​
},​
'per_page': {​
'type':​
'integer',​
'description':​
'The number of results per page (max 100). For more
information, see "Using pagination in the REST API." Default: 30.'​
},​
'page': {​
'type':​
'integer',​
'description':​
'The page number of the results to fetch. For more
information, see "Using pagination in the REST API." Default: 1.'​
}​
},​
'required': ['owner', 'repo']​
}​
})​
def list_repository_pull_requests(​
owner: str,​
repo: str,​
state: Optional[str] = 'open',​
sort: Optional[str] = 'created',​
direction: Optional[str] = 'desc',​
per_page: Optional[int] = 30,​
page: Optional[int] = 1) -> List[Dict[str, Any]]
List and filter repository pull requests.

This function lists and filters pull requests for a specified repository.

It allows querying for pull requests based on their state (open, closed, or all).

Results can be sorted by various criteria such as creation date,

update date, popularity (number of comments), or by identifying long-running

pull requests. The direction of sorting (ascending or descending) can also be

specified. Pagination options are available to control the number of results

per page and to fetch specific pages of results, facilitating the handling of

large datasets.

Args:
owner (str): The account owner of the repository. The name is not case sensitive.

repo (str): The name of the repository without the .git extension. The name is not case
sensitive.

state (Optional[str]): Filter by state. Possible values: 'open', 'closed', 'all'. Default: 'open'.

sort (Optional[str]): What to sort results by. 'popularity' will sort by the number of
comments. 'long-running' will sort by date created and will limit the results to pull requests
that have been open for more than a month and have had activity within the past month.
Possible values: 'created', 'updated', 'popularity', 'long-running'. Default: 'created'.

direction (Optional[str]): The direction of the sort. Possible values: 'asc', 'desc'. Default:
'desc' when 'sort' is 'created' or not specified, otherwise 'asc'.

per_page (Optional[int]): The number of results per page (max 100). For more information,
see "Using pagination in the REST API." Default: 30.

page (Optional[int]): The page number of the results to fetch. For more information, see
"Using pagination in the REST API." Default: 1.

Returns:
List[Dict[str, Any]]: A list of pull request dictionaries matching the filter criteria with the
following fields:

id (int): Unique identifier for the pull request.

node_id (str): The node ID of the pull request.

number (int): PR number is unique per repository

title (str): The title of the pull request.

user (Dict[str, Any]): The user who created the pull request. Contains the following fields:

node_id (Optional[str]): Global node ID of the user.

type (Optional[str]): Type of account, e.g., 'User' or 'Organization'.

site_admin (Optional[bool]): Whether the user is a site administrator.

labels (List[Dict[str, Any]]): List of labels associated with the pull request. Each label
contains the following fields:

id (int): Unique identifier for the label.

node_id (str): The node ID of the label.

repository_id (int): ID of the repository this label belongs to.

name (str): The name of the label.

color (str): The color of the label.

description (Optional[str]): The description of the label.

default (Optional[bool]): Whether the label is the default label for the repository.

state (str): The state of the pull request.

locked (bool): Whether the pull request is locked.

assignee (Optional[Dict[str, Any]]): The user assigned to the pull request. Contains the
following fields:

node_id (Optional[str]): Global node ID of the user.

type (Optional[str]): Type of account, e.g., 'User' or 'Organization'.

site_admin (Optional[bool]): Whether the user is a site administrator.

assignees (List[Dict[str, Any]]): List of users assigned to the pull request, each containing the
following fields:

node_id (Optional[str]): Global node ID of the user.

type (Optional[str]): Type of account, e.g., 'User' or 'Organization'.

site_admin (Optional[bool]): Whether the user is a site administrator.

milestone: Optional[Dict[str, Any]]: The milestone associated with the pull request. Contains
the following fields:
id (int): Unique identifier for the milestone.

node_id (str): The node ID of the milestone.

repository_id (int): ID of the repository this milestone belongs to.

number (int): The number of the milestone, unique per repository.

title (str): The title of the milestone.

description (Optional[str]): The description of the milestone.

creator (Optional[Dict[str, Any]]): The user who created the milestone. Contains the
following fields:

node_id (Optional[str]): Global node ID of the user.

type (Optional[str]): Type of account, e.g., 'User' or 'Organization'.

site_admin (Optional[bool]): Whether the user is a site administrator.

open_issues (int): The number of open issues associated with the milestone.

closed_issues (int): The number of closed issues associated with the milestone.

state (str): The state of the milestone.

created_at (datetime): The date and time the milestone was created.

updated_at (datetime): The date and time the milestone was last updated.

closed_at (Optional[datetime]): The date and time the milestone was closed.

due_on (Optional[datetime]): The date and time the milestone is due.

created_at (datetime): The date and time the pull request was created.

updated_at (datetime): The date and time the pull request was last updated.

closed_at (Optional[datetime]): The date and time the pull request was closed.

merged_at (Optional[datetime]): The date and time the pull request was merged.

body (Optional[str]): The body of the pull request.

author_association (str): The author association of the pull request.

Could be "COLLABORATOR", "CONTRIBUTOR", "FIRST_TIMER",

"FIRST_TIME_CONTRIBUTOR",

"MANNEQUIN", "MEMBER", "NONE", or "OWNER".

draft (Optional[bool]): Whether the pull request is a draft.

merged (Optional[bool]): Whether the pull request was merged.

mergeable (Optional[bool]): Whether the pull request can be merged.

rebaseable (Optional[bool]): Whether the pull request can be rebased.

mergeable_state (Optional[str]): The mergeable state of the pull request. Could be "clean",
"dirty", or "unknown".

merged_by (Optional[Dict[str, Any]]): The user who merged the pull request. Contains the
following fields:

node_id (Optional[str]): Global node ID of the user.

type (Optional[str]): Type of account, e.g., 'User' or 'Organization'.

site_admin (Optional[bool]): Whether the user is a site administrator.

comments (Optional[int]): The number of comments on the pull request.

review_comments (Optional[int]): The number of review comments on the pull request.

commits (Optional[int]): The number of commits in the pull request.

additions (Optional[int]): The number of additions in the pull request.

deletions (Optional[int]): The number of deletions in the pull request.

changed_files (Optional[int]): The number of changed files in the pull request.

head (Dict[str, Any]): The head branch of the pull request. Contains the following fields:

label (str): The label of the head branch.

ref (str): The name of the head branch.

sha (str): The SHA of the head branch.

user (Dict[str, Any]): The user who created the head branch. Contains the following fields:

node_id (Optional[str]): Global node ID of the user.

type (Optional[str]): Type of account, e.g., 'User' or 'Organization'.

site_admin (Optional[bool]): Whether the user is a site administrator.

repo (Dict[str, Any]): The repository of the head branch. Contains the following fields:

id (int): Unique identifier for the repository.

node_id (str): A global identifier for the repository.

name (str): The name of the repository.

full_name (str): The full name of the repository (owner/name).

private (bool): Indicates whether the repository is private.

owner (Dict[str, Any]): The user or organization that owns the repository. Contains the
following fields:

node_id (Optional[str]): Global node ID of the user.

type (Optional[str]): Type of account, e.g., 'User' or 'Organization'.

site_admin (Optional[bool]): Whether the user is a site administrator.

description (Optional[str]): A description of the repository.

fork (bool): Indicates whether the repository is a fork.

created_at (datetime): Timestamp for when the repository was created.

updated_at (datetime): Timestamp for when the repository was last updated.

pushed_at (datetime): Timestamp for when the repository was last pushed to.

size (int): The size of the repository in kilobytes.

stargazers_count (Optional[int]): Number of stargazers.

watchers_count (Optional[int]): Number of watchers.

language (Optional[str]): The primary language of the repository.

has_issues (Optional[bool]): Whether issues are enabled.

has_projects (Optional[bool]): Whether projects are enabled.

has_downloads (Optional[bool]): Whether downloads are enabled.

has_wiki (Optional[bool]): Whether the wiki is enabled.

has_pages (Optional[bool]): Whether GitHub Pages are enabled.

forks_count (Optional[int]): Number of forks.

archived (Optional[bool]): Whether the repository is archived.

disabled (Optional[bool]): Whether the repository is disabled.

open_issues_count (Optional[int]): Number of open issues.

license (Optional[Dict[str, Any]]): The license of the repository. Contains the following fields:

key (str): The key of the license.

name (str): The name of the license.

spdx_id (str): The SPDX identifier for the license.

allow_forking (Optional[bool]): Whether forking is allowed.

is_template (Optional[bool]): Whether this repository is a template repository.

web_commit_signoff_required (Optional[bool]): Whether web commit signoff is required.

topics (Optional[List[str]]): The topics of the repository.

visibility (Optional[str]): The visibility of the repository.

default_branch (Optional[str]): The default branch of the repository.

forks (Optional[int]): Number of forks.

open_issues (Optional[int]): Number of open issues.

watchers (Optional[int]): Number of watchers.

score (Optional[float]): Search score if from search results.

fork_details (Optional[Dict[str, Any]]): Details about the fork lineage if the repository is a
fork, containig the following keys:

parent_id (int): The ID of the direct parent repository.

parent_full_name (str): The full name of the direct parent repository.

source_id (int): The ID of the ultimate source repository in the fork network.

source_full_name (str): The full name of the ultimate source repository.

base (Dict[str, Any]): The base branch of the pull request. Contains the following fields:

label (str): The label of the head branch.

ref (str): The name of the head branch.

sha (str): The SHA of the head branch.

user (Dict[str, Any]): The user who created the head branch. Contains the following fields:
node_id (Optional[str]): Global node ID of the user.

type (Optional[str]): Type of account, e.g., 'User' or 'Organization'.

site_admin (Optional[bool]): Whether the user is a site administrator.

repo (Dict[str, Any]): The repository of the head branch. Contains the following fields:

id (int): Unique identifier for the repository.

node_id (str): A global identifier for the repository.

name (str): The name of the repository.

full_name (str): The full name of the repository (owner/name).

private (bool): Indicates whether the repository is private.

owner (Dict[str, Any]): The user or organization that owns the repository. Contains the
following fields:

node_id (Optional[str]): Global node ID of the user.

type (Optional[str]): Type of account, e.g., 'User' or 'Organization'.

site_admin (Optional[bool]): Whether the user is a site administrator.

description (Optional[str]): A description of the repository.

fork (bool): Indicates whether the repository is a fork.

created_at (datetime): Timestamp for when the repository was created.

updated_at (datetime): Timestamp for when the repository was last updated.

pushed_at (datetime): Timestamp for when the repository was last pushed to.

size (int): The size of the repository in kilobytes.

stargazers_count (Optional[int]): Number of stargazers.

watchers_count (Optional[int]): Number of watchers.

language (Optional[str]): The primary language of the repository.

has_issues (Optional[bool]): Whether issues are enabled.

has_projects (Optional[bool]): Whether projects are enabled.

has_downloads (Optional[bool]): Whether downloads are enabled.

has_wiki (Optional[bool]): Whether the wiki is enabled.

has_pages (Optional[bool]): Whether GitHub Pages are enabled.

forks_count (Optional[int]): Number of forks.

archived (Optional[bool]): Whether the repository is archived.

disabled (Optional[bool]): Whether the repository is disabled.

open_issues_count (Optional[int]): Number of open issues.

license (Optional[Dict[str, Any]]): The license of the repository. Contains the following fields:

key (str): The key of the license.

name (str): The name of the license.

spdx_id (str): The SPDX identifier for the license.

allow_forking (Optional[bool]): Whether forking is allowed.

is_template (Optional[bool]): Whether this repository is a template repository.

web_commit_signoff_required (Optional[bool]): Whether web commit signoff is required.

topics (Optional[List[str]]): The topics of the repository.

visibility (Optional[str]): The visibility of the repository.

default_branch (Optional[str]): The default branch of the repository.

forks (Optional[int]): Number of forks.

open_issues (Optional[int]): Number of open issues.

watchers (Optional[int]): Number of watchers.

score (Optional[float]): Search score if from search results.

fork_details (Optional[Dict[str, Any]]): Details about the fork lineage if the repository is a
fork, containig the following keys:

parent_id (int): The ID of the direct parent repository.

parent_full_name (str): The full name of the direct parent repository.

source_id (int): The ID of the ultimate source repository in the fork network.

source_full_name (str): The full name of the ultimate source repository.

Raises:
NotFoundError: If the repository does not exist.

ValidationError: If filter parameters are invalid.

RateLimitError: If the API rate limit is exceeded.

update_pull_request
@tool_spec(​
spec={​
'name': 'update_pull_request',​
'description':​
""" Update an existing pull request in a GitHub repository.​
​
Updates an existing pull request in a GitHub repository. This
function allows​
for updating attributes of a pull request such as its title,
body, state​
(e.g., 'open' or 'closed'), the base branch it targets, and
whether​
maintainers are permitted to make modifications to it. """,​
'parameters': {​
'type': 'object',​
'properties': {​
'owner': {​
'type': 'string',​
'description': 'The owner of the repository.'​
},​
'repo': {​
'type': 'string',​
'description': 'The name of the repository.'​
},​
'pull_number': {​
'type': 'integer',​
'description': 'The number identifying the pull
request.'​
},​
'title': {​
'type':​
'string',​
'description':​
'The new title for the pull request. Defaults to
None.'​
},​
'body': {​
'type':​
'string',​
'description':​
'The new body content for the pull request. Defaults
to None.'​
},​
'state': {​
'type':​
'string',​
'description':​
""" The new state of the pull request (e.g., 'open'
or 'closed').​
Defaults to None. """​
},​
'base': {​
'type':​
'string',​
'description':​
""" The name of the branch to which the changes are
proposed​
(the base branch). Defaults to None. """​
},​
'maintainer_can_modify': {​
'type':​
'boolean',​
'description':​
""" Specifies whether maintainers can modify​
the pull request. Defaults to False. """​
}​
},​
'required': ['owner', 'repo', 'pull_number']​
}​
})​
def update_pull_request(owner: str,​
repo: str,​
pull_number: int,​
title: Optional[str] = None,​
body: Optional[str] = None,​
state: Optional[str] = None,​
base: Optional[str] = None,​
maintainer_can_modify: bool = False) -> Dict[str,
Any]

Update an existing pull request in a GitHub repository.

Updates an existing pull request in a GitHub repository. This function allows

for updating attributes of a pull request such as its title, body, state

(e.g., 'open' or 'closed'), the base branch it targets, and whether

maintainers are permitted to make modifications to it.

Args:
owner (str): The owner of the repository.

repo (str): The name of the repository.

pull_number (int): The number identifying the pull request.

title (Optional[str]): The new title for the pull request. Defaults to None.

body (Optional[str]): The new body content for the pull request. Defaults to None.

state (Optional[str]): The new state of the pull request (e.g., 'open' or 'closed').

Defaults to None.

base (Optional[str]): The name of the branch to which the changes are proposed

(the base branch). Defaults to None.

maintainer_can_modify (bool): Specifies whether maintainers can modify

the pull request. Defaults to False.

Returns:
Dict[str, Any]: A dictionary containing the details of the updated pull request.

Key fields that can be directly updated via this method include title,

body, state, base, and maintainer_can_modify. The dictionary

structure includes the following fields (among others; this list is

representative and omits URL-based fields):

id (int): Unique identifier for the pull request.

number (int): Pull request number within the repository.

state (str): The state of the pull request (e.g., 'open', 'closed').

title (str): The title of the pull request.

body (Optional[str]): The body text of the pull request.

user (Dict[str, Any]): The user who created the pull request. Contains fields such as:

login (str): Username of the user.

id (int): Unique identifier for the user.

type (str): Type of the user (e.g., 'User', 'Bot').

created_at (str): ISO 8601 timestamp for when the pull request was created.

updated_at (str): ISO 8601 timestamp for when the pull request was last updated.

closed_at (Optional[str]): ISO 8601 timestamp for when the pull request was closed.

merged_at (Optional[str]): ISO 8601 timestamp for when the pull request was merged.

base (Dict[str, Any]): Details of the base branch. Contains fields such as:

label (str): The label of the base branch (e.g., 'owner:main').

ref (str): The reference of the base branch (e.g., 'main').

sha (str): The SHA of the commit at the tip of the base branch.

repo (Dict[str, Any]): The repository of the base branch. Contains fields such as:

id (int): Unique identifier of the repository.

name (str): Name of the repository.

full_name (str): Full name of the repository (e.g., 'owner/repo').

private (bool): Whether the repository is private.

head (Dict[str, Any]): Details of the head branch. Contains fields such as:

label (str): The label of the head branch.

ref (str): The reference of the head branch.

sha (str): The SHA of the commit at the tip of the head branch.

repo (Dict[str, Any]): The repository of the head branch (may be null if fork was deleted).
Contains fields such as:

id (int): Unique identifier of the repository.

name (str): Name of the repository.

full_name (str): Full name of the repository.

private (bool): Whether the repository is private.

draft (bool): Whether the pull request is a draft.

merged (bool): Whether the pull request has been merged.

mergeable (Optional[bool]): Whether the pull request is mergeable.

mergeable_state (str): State of the mergeability check (e.g., 'clean', 'dirty', 'unknown').

merged_by (Optional[Dict[str, Any]]): The user who merged the pull request. Contains fields
such as:

login (str): Username of the user.

id (int): Unique identifier for the user.

type (str): Type of the user.

comments_count (int): Number of issue comments on the pull request.

review_comments_count (int): Number of commit comments on the pull request.

maintainer_can_modify (bool): Indicates whether maintainers can modify the pull request.

commits_count (int): Number of commits in the pull request.

additions_count (int): Number of lines added in the pull request.

deletions_count (int): Number of lines deleted in the pull request.

changed_files_count (int): Number of files changed in the pull request.

Raises:
NotFoundError: If the repository or pull request does not exist.

ValidationError: If input parameters for update are invalid (e.g., invalid

state value, such as attempting to set a state other than 'open'

or 'closed').

UnprocessableEntityError: If the update cannot be applied (e.g., trying to

change base to an invalid branch, or a merge conflict prevents

the update).

ForbiddenError: If the user does not have permission to update the pull request.

update_pull_request_branch
@tool_spec(​
spec={​
'name': 'update_pull_request_branch',​
'description':​
""" Update a pull request branch with the latest changes from the
base branch.​
​
This function updates a pull request branch by incorporating the
most recent changes​
from its base branch. If an `expected_head_sha` is provided, the
update​
will only proceed if this SHA matches the current head of the
pull request's​
branch, ensuring the update is based on the expected state. """,​
'parameters': {​
'type': 'object',​
'properties': {​
'owner': {​
'type':​
'string',​
'description':​
'The account owner of the repository. The name is not
case sensitive.'​
},​
'repo': {​
'type':​
'string',​
'description':​
""" The name of the repository without the .git
extension. The name​
is not case sensitive. """​
},​
'pull_number': {​
'type': 'integer',​
'description':​
'The number that identifies the pull request.'​
},​
'expected_head_sha': {​
'type':​
'string',​
'description':​
""" The expected SHA of the pull request's HEAD​
ref. This is the most recent commit on the pull
request's branch. If the​
expected SHA does not match the pull request's HEAD,
you will receive a​
422 Unprocessable Entity status. You can use the
"List commits" endpoint​
to find the most recent commit SHA. Defaults to None.
"""​
}​
},​
'required': ['owner', 'repo', 'pull_number']​
}​
})​
def update_pull_request_branch(​
owner: str,​
 repo: str,​
pull_number: int,​
expected_head_sha: Optional[str] = None) -> Dict[str, str]

Update a pull request branch with the latest changes from the base branch.

This function updates a pull request branch by incorporating the most recent changes

from its base branch. If an `expected_head_sha` is provided, the update

will only proceed if this SHA matches the current head of the pull request's

branch, ensuring the update is based on the expected state.

Args:
owner (str): The account owner of the repository. The name is not case sensitive.

repo (str): The name of the repository without the .git extension. The name

is not case sensitive.

pull_number (int): The number that identifies the pull request.

expected_head_sha (Optional[str]): The expected SHA of the pull request's HEAD

ref. This is the most recent commit on the pull request's branch. If the

expected SHA does not match the pull request's HEAD, you will receive a

422 Unprocessable Entity status. You can use the "List commits" endpoint

to find the most recent commit SHA. Defaults to None.

Returns:
Dict[str, str]: A dictionary confirming the branch update request. It contains

the following key:

message (str): A human-readable message indicating the status of the update

request, such as confirmation of acceptance or scheduling (e.g.,

'Accepted', 'Update scheduled').

Raises:
NotFoundError: If the repository or pull request does not exist.

ConflictError: If the branch update cannot be performed (e.g., merge conflicts,

or if `expected_head_sha` does not match the current head of the pull

request's branch).

ForbiddenError: If the user does not have sufficient permissions to update the

pull request branch, or if branch protection rules prevent the update.

add_pull_request_review_comment
@tool_spec(​
spec={​
'name': 'add_pull_request_review_comment',​
'description':​
""" Add a review comment to a pull request or reply to an
existing comment.​
​
This function adds a review comment to a specified pull request
or replies to an​
existing comment. Depending on whether it's a new comment or a
reply,​
different parameters are required. For new comments, context like
commit SHA,​
file path, and line number may be necessary. For replies, the ID
of the​
parent comment is used to inherit context. """,​
'parameters': {​
'type': 'object',​
'properties': {​
'owner': {​
'type':​
'string',​
'description':​
'The account owner of the repository. The name is not
case sensitive.'​
},​
'repo': {​
'type':​
'string',​
'description':​
'The name of the repository. The name is not case
sensitive.'​
},​
'pull_number': {​
'type': 'integer',​
'description':​
'The number that identifies the pull request.'​
},​
'body': {​
'type': 'string',​
'description': 'The text of the review comment.'​
},​
 'commit_id': {​
'type':​
'string',​
'description':​
""" The SHA of the commit to comment on. Required if​
`in_reply_to` is not provided and the comment is not
a reply. Defaults to None. """​
},​
'path': {​
'type':​
'string',​
'description':​
""" The relative path to the file that necessitates a
comment.​
Required if `in_reply_to` is not provided and the
comment is not a reply. Defaults to None. """​
},​
'line': {​
'type':​
'integer',​
'description':​
""" The line of the blob in the pull request diff
that the​
comment applies to. For a multi-line comment, this is
the last line​
of the range. Required for new line-level comments
(when `subject_type`​
is 'line' or inferred as such). Defaults to None. """​
},​
'side': {​
'type':​
'string',​
'description':​
""" The side of the diff to comment on. Valid values
are​
'LEFT' (for the old version) or 'RIGHT' (for the new
version).​
Defaults to 'RIGHT' if `line` is provided. Only used
for line-level​
comments. Defaults to None. """​
},​
'start_line': {​
'type':​
'integer',​
'description':​
""" For a multi-line comment, the first line of the​
range. `line` should be the end line. Only used for
line-level comments. Defaults to None. """​
},​
 'start_side': {​
'type':​
'string',​
'description':​
""" The side of the diff for `start_line`. Valid
values​
are 'LEFT' or 'RIGHT'. Defaults to the `side`
parameter if not​
provided. Only used for multi-line comments. Defaults
to None. """​
},​
'subject_type': {​
'type':​
'string',​
'description':​
""" The type of subject for the comment. Valid values​
are 'line' or 'file'. If 'file', line-specific
parameters (`line`,​
`side`, `start_line`, `start_side`) are ignored. If
'line', they are​
used. If not provided, the API may infer based on
other parameters​
(e.g., presence of `line`). Defaults to None. """​
},​
'in_reply_to': {​
'type':​
'integer',​
'description':​
""" The ID of an existing comment to which this​
comment is a reply. If provided, parameters like
`commit_id`, `path`,​
`line`, `side`, `start_line`, `start_side`, and
`subject_type` are​
typically ignored as the reply inherits context from
the parent comment. Defaults to None. """​
}​
},​
'required': ['owner', 'repo', 'pull_number', 'body']​
}​
})​
def add_pull_request_review_comment(​
owner: str,​
repo: str,​
pull_number: int,​
body: str,​
commit_id: Optional[str] = None,​
path: Optional[str] = None,​
line: Optional[int] = None,​
side: Optional[str] = None,​
 start_line: Optional[int] = None,​
start_side: Optional[str] = None,​
subject_type: Optional[str] = None,​
in_reply_to: Optional[int] = None) -> Dict[str, Any]

Add a review comment to a pull request or reply to an existing comment.

This function adds a review comment to a specified pull request or replies to an

existing comment. Depending on whether it's a new comment or a reply,

different parameters are required. For new comments, context like commit SHA,

file path, and line number may be necessary. For replies, the ID of the

parent comment is used to inherit context.

Args:
owner (str): The account owner of the repository. The name is not case sensitive.

repo (str): The name of the repository. The name is not case sensitive.

pull_number (int): The number that identifies the pull request.

body (str): The text of the review comment.

commit_id (Optional[str]): The SHA of the commit to comment on. Required if

`in_reply_to` is not provided and the comment is not a reply. Defaults to None.

path (Optional[str]): The relative path to the file that necessitates a comment.

Required if `in_reply_to` is not provided and the comment is not a reply. Defaults to None.

line (Optional[int]): The line of the blob in the pull request diff that the

comment applies to. For a multi-line comment, this is the last line

of the range. Required for new line-level comments (when `subject_type`

is 'line' or inferred as such). Defaults to None.

side (Optional[str]): The side of the diff to comment on. Valid values are

'LEFT' (for the old version) or 'RIGHT' (for the new version).

Defaults to 'RIGHT' if `line` is provided. Only used for line-level

comments. Defaults to None.

start_line (Optional[int]): For a multi-line comment, the first line of the

range. `line` should be the end line. Only used for line-level comments. Defaults to None.

start_side (Optional[str]): The side of the diff for `start_line`. Valid values

are 'LEFT' or 'RIGHT'. Defaults to the `side` parameter if not

provided. Only used for multi-line comments. Defaults to None.

subject_type (Optional[str]): The type of subject for the comment. Valid values

are 'line' or 'file'. If 'file', line-specific parameters (`line`,

`side`, `start_line`, `start_side`) are ignored. If 'line', they are

used. If not provided, the API may infer based on other parameters

(e.g., presence of `line`). Defaults to None.

in_reply_to (Optional[int]): The ID of an existing comment to which this

comment is a reply. If provided, parameters like `commit_id`, `path`,

`line`, `side`, `start_line`, `start_side`, and `subject_type` are

typically ignored as the reply inherits context from the parent comment. Defaults to None.

Returns:
Dict[str, Any]: A dictionary containing the details of the newly created review comment.

This dictionary has the following keys:

id (int): The unique identifier for the comment.

pull_request_review_id (Optional[int]): The ID of the review this comment

is part of. Null if it's a standalone comment not submitted as

part of a pull request review.

user (Dict[str, Any]): Object containing details about the commenter. This

dictionary includes the following keys:

login (str): The username of the commenter.

id (int): The unique identifier for the user.

type (str): The type of account (e.g., 'User', 'Bot').

body (str): The text content of the comment.

commit_id (str): The SHA of the commit to which the comment pertains.

path (str): The relative path of the file commented on.

position (Optional[int]): The line index in the diff to which the comment

pertains (lines down in the diff hunk). Null if the comment is on

a file or if position is not applicable.

created_at (str): The ISO 8601 timestamp for when the comment was created.

updated_at (str): The ISO 8601 timestamp for when the comment was last

updated.

Raises:
NotFoundError: If the specified `owner`/`repo`, `pull_number`, `commit_id`

(if provided for a new comment), or `in_reply_to` (if provided for

a reply) does not exist.

ValidationError: If required input parameters are missing or invalid. For

example, `body` is always required. If `in_reply_to` is not

provided (i.e., creating a new comment, not a reply), then

`commit_id` and `path` are typically required. For new line-level

comments, `line` is also required. Parameters may also be invalid

if their types are incorrect or values are out of supported

range/format.

UnprocessableEntityError: If the comment cannot be posted (e.g., the `line`

is not part of the diff, or the `path` is not part of the diff for

the given `commit_id`).

ForbiddenError: If the authenticated user does not have permission to create

a comment on the pull request.

merge_pull_request
@tool_spec(​
spec={​
'name': 'merge_pull_request',​
 'description': 'Merge a pull request.',​
'parameters': {​
'type': 'object',​
'properties': {​
'owner': {​
'type': 'string',​
'description': 'The owner of the repository.'​
},​
'repo': {​
'type': 'string',​
'description': 'The name of the repository.'​
},​
'pull_number': {​
'type': 'integer',​
'description': 'The number identifying the pull
request.'​
},​
'commit_title': {​
'type':​
'string',​
'description':​
'An optional title for the merge commit. Defaults to
None.'​
},​
'commit_message': {​
'type':​
'string',​
'description':​
'An optional message for the merge commit. Defaults
to None.'​
},​
'merge_method': {​
'type':​
'string',​
'description':​
'An optional merge method to use. Defaults to None.'​
}​
},​
'required': ['owner', 'repo', 'pull_number']​
}​
})​
def merge_pull_request(owner: str,​
repo: str,​
pull_number: int,​
commit_title: Optional[str] = None,​
commit_message: Optional[str] = None,​
merge_method: Optional[str] = None) -> Dict[str,
Any]
Merge a pull request.

Args:
owner (str): The owner of the repository.

repo (str): The name of the repository.

pull_number (int): The number identifying the pull request.

commit_title (Optional[str]): An optional title for the merge commit. Defaults to None.

commit_message (Optional[str]): An optional message for the merge commit. Defaults to

None.

merge_method (Optional[str]): An optional merge method to use. Defaults to None.

Returns:
Dict[str, Any]: A dictionary confirming the merge status. It contains the following fields:

sha (str): The SHA (Secure Hash Algorithm) identifier of the merge commit.

merged (bool): Indicates if the merge was successfully completed (True) or not (False).

message (str): A human-readable message describing the outcome of the merge attempt
(e.g., 'Pull Request successfully merged', 'Merge conflict').

Raises:
NotFoundError: If the repository or pull request does not exist.

MethodNotAllowedError: If the pull request is not mergeable (e.g., conflicts, checks

pending).

ConflictError: If the merge cannot be performed due to conflicts or if the head commit of the
pull request has changed since the merge was initiated.

ValidationError: If the merge method is invalid, or other input parameters are incorrect or
missing.

ForbiddenError: If the authenticated user does not have permission to merge the pull
request.

get_pull_request_files
@tool_spec(​
spec={​
'name': 'get_pull_request_files',​
'description': """ Get the list of files changed in a pull
request.​
​
This function retrieves the list of files changed in a specified
pull request.​
The pull request is identified using the `owner` of the
repository,​
the `repo` name, and the `pull_number`. """,​
'parameters': {​
'type': 'object',​
'properties': {​
'owner': {​
'type': 'string',​
'description': 'The owner of the repository.'​
},​
'repo': {​
'type': 'string',​
'description': 'The name of the repository.'​
},​
'pull_number': {​
'type': 'integer',​
'description': 'The number of the pull request.'​
}​
},​
'required': ['owner', 'repo', 'pull_number']​
}​
})​
def get_pull_request_files(owner: str, repo: str,​
pull_number: int) -> List[Dict[str, Any]]

Get the list of files changed in a pull request.

This function retrieves the list of files changed in a specified pull request.

The pull request is identified using the `owner` of the repository,

the `repo` name, and the `pull_number`.

Args:
owner (str): The owner of the repository.

repo (str): The name of the repository.

pull_number (int): The number of the pull request.

Returns:
List[Dict[str, Any]]: A list of dictionaries, where each dictionary details a file

changed in the pull request. Each dictionary has the following keys:

sha (str): The SHA (Secure Hash Algorithm) identifier of the file blob.

filename (str): The relative path of the file within the repository.
status (str): The status of the file ('added', 'modified', 'removed', or 'renamed').

additions (int): The number of lines added to the file.

deletions (int): The number of lines deleted from the file.

changes (int): The total number of lines changed in the file (sum of additions and deletions).

patch (Optional[str]): The patch data for the file. May be null for binary files or when not
available.

previous_filename (str): The previous filename (only present for renamed files).

Raises:
ValidationError: If the input parameters are invalid.

NotFoundError: If the repository or pull request does not exist.

get_pull_request_status
@tool_spec(​
spec={​
'name': 'get_pull_request_status',​
'description':​
""" Get the combined status of all status checks for a pull
request.​
​
This function retrieves the combined status of all status checks
for a specified pull request.​
The pull request is identified by its owner, repository, and pull
number.​
The returned status includes an overall state, commit SHA, total
check count,​
and a detailed list of individual status checks. """,​
'parameters': {​
'type': 'object',​
'properties': {​
'owner': {​
'type': 'string',​
'description': 'The owner of the repository.'​
},​
'repo': {​
'type': 'string',​
'description': 'The name of the repository.'​
},​
'pull_number': {​
'type': 'integer',​
'description': 'The number identifying the pull
request.'​
}​
 },​
'required': ['owner', 'repo', 'pull_number']​
}​
})​
def get_pull_request_status(owner: str, repo: str,​
pull_number: int) -> Dict[str, Any]

Get the combined status of all status checks for a pull request.

This function retrieves the combined status of all status checks for a specified pull request.

The pull request is identified by its owner, repository, and pull number.

The returned status includes an overall state, commit SHA, total check count,

and a detailed list of individual status checks.

Args:
owner (str): The owner of the repository.

repo (str): The name of the repository.

pull_number (int): The number identifying the pull request.

Returns:
Dict[str, Any]: A dictionary representing the combined status of a commit. It contains the
following keys:

state (str): The overall status (e.g., 'pending', 'success', 'failure', 'error').

sha (str): The SHA of the commit for which status is reported.

total_count (int): The total number of status checks.

statuses (List[Dict[str, Any]]): A list of individual status check objects. Each dictionary

in this list details a specific status check and contains the following fields:

state (str): State of the specific check (e.g., 'pending', 'success', 'failure', 'error').

context (str): The name or identifier of the status check service (e.g., 'ci/travis-ci', 'lint').

description (Optional[str]): A short human-readable description of the status provided by

the service.

Raises:
NotFoundError: If the repository or pull request (or its head commit) does not exist.

ValidationError: If any of the input parameter is Invalid.

get_pull_request_reviews
@tool_spec(​
spec={​
'name': 'get_pull_request_reviews',​
'description': """ Lists all reviews for a specified pull
request.​
​
Lists all reviews for a specified pull request. The list of
reviews returns in chronological order. """,​
'parameters': {​
'type': 'object',​
'properties': {​
'owner': {​
'type':​
'string',​
'description':​
'The account owner of the repository. The name is not
case sensitive.'​
},​
'repo': {​
'type':​
'string',​
'description':​
'The name of the repository without the .git
extension. The name is not case sensitive.'​
},​
'pull_number': {​
'type':​
'integer',​
'description':​
'The number that identifies the pull request. Must be
a positive integer.'​
}​
},​
'required': ['owner', 'repo', 'pull_number']​
}​
})​
def get_pull_request_reviews(owner: str, repo: str,​
pull_number: int) -> List[Dict[str, Any]]

Lists all reviews for a specified pull request.

Lists all reviews for a specified pull request. The list of reviews returns in chronological
order.

Args:
owner (str): The account owner of the repository. The name is not case sensitive.
repo (str): The name of the repository without the .git extension. The name is not case
sensitive.

pull_number (int): The number that identifies the pull request. Must be a positive integer.

Returns:
List[Dict[str, Any]]: A list of dictionaries, where each dictionary represents a review

for the pull request. Each dictionary has the following keys:

id (Optional[int]): The unique ID of the review.

node_id (Optional[str]): The global node ID of the review.

user (Dict[str, Any]): A dictionary representing the user who submitted the review. This

dictionary contains:

login (Optional[str]): The username of the user.

id (Optional[int]): The unique ID of the user.

body (Optional[str]): The body of the review.

state (str): The state of the review (e.g., 'APPROVED', 'CHANGES_REQUESTED',

'COMMENTED', 'DISMISSED', 'PENDING').

commit_id (str): The SHA of the commit that the review pertains to.

submitted_at (Optional[str]): ISO 8601 timestamp of when the review was submitted.

author_association (str): The relationship of the reviewer to the repository.

Raises:
TypeError: If 'owner' or 'repo' is not a string, or if 'pull_number' is not an integer.

ValueError: If 'pull_number' is not a positive integer.

NotFoundError: If the repository or pull request does not exist.

get_pull_request_review_comments
@tool_spec(​
spec={​
'name': 'get_pull_request_review_comments',​
'description': """ Get the review comments on a pull request.​
​
Retrieves all review comments associated with a specific pull
request.​
The pull request is identified by the repository owner's
identifier,​
the repository name, and the pull request number. """,​
'parameters': {​
'type': 'object',​
'properties': {​
'owner': {​
'type':​
'string',​
'description':​
'The login name or identifier of the repository
owner.'​
},​
'repo': {​
'type': 'string',​
'description': 'The name of the repository.'​
},​
'pull_number': {​
'type': 'integer',​
'description': 'The number identifying the pull
request.'​
}​
},​
'required': ['owner', 'repo', 'pull_number']​
}​
})​
def get_pull_request_review_comments(owner: str, repo: str,​
pull_number: int) -> List[Dict[str,
Any]]

Get the review comments on a pull request.

Retrieves all review comments associated with a specific pull request.

The pull request is identified by the repository owner's identifier,

the repository name, and the pull request number.

Args:
owner (str): The login name or identifier of the repository owner.

repo (str): The name of the repository.

pull_number (int): The number identifying the pull request.

Returns:
List[Dict[str, Any]]: A list of dictionaries, where each dictionary represents a review
comment

for the pull request. Each dictionary contains the following keys:
id (int): The unique ID of the comment.

node_id (str): The global node ID of the comment.

pull_request_review_id (Optional[int]): The ID of the review this comment belongs to. Null if
the comment is not part of a review.

user (Dict[str, Any]): The user who created the comment. It includes the following keys:

login (str): The login name of the user.

id (int): The unique ID of the user.

body (str): The text of the comment.

commit_id (str): The SHA of the commit the comment is on.

path (str): The relative path of the file commented on.

position (Optional[int]): The line index in the diff to which the comment applies.

original_position (Optional[int]): The original line index in the diff. Null for file-level
comments.

diff_hunk (Optional[str]): The diff hunk where the comment appears. Null if not applicable
or available.

created_at (str): ISO 8601 timestamp of when the comment was created.

updated_at (str): ISO 8601 timestamp of when the comment was last updated.

author_association (str): The relationship of the comment author to the repository.

start_line (Optional[int]): The first line of the range of the comment if it spans multiple lines.
Null for single-line comments.

original_start_line (Optional[int]): Original first line of a multi-line comment's range. Null for
single-line comments.

start_side (Optional[str]): The side of the diff to which the first line of a multi-line comment

applies (e.g., 'LEFT' or 'RIGHT'). Null for single-line comments.

line (Optional[int]): The line of the blob to which the comment applies. Null for file-level
comments.

original_line (Optional[int]): Original line of the blob. Null for file-level comments.

side (Optional[str]): The side of the diff to which the comment applies (e.g., 'LEFT' or
'RIGHT'). Null for file-level comments.
Raises:
NotFoundError: If the repository or pull request does not exist.

TypeError: If an input parameter has an invalid type.

ValueError: If an input parameter has an invalid value.

get_pull_request_details
@tool_spec(​
spec={​
'name': 'get_pull_request_details',​
'description': """ Get details of a specific pull request.​
​
This function gets details of a specific pull request. It uses
the provided​
owner, repository name, and pull request number to identify and
retrieve​
the comprehensive details of the pull request. """,​
'parameters': {​
'type': 'object',​
'properties': {​
'owner': {​
'type': 'string',​
'description': 'The account owner of the repository.'​
},​
'repo': {​
'type': 'string',​
'description': 'The name of the repository.'​
},​
'pull_number': {​
'type': 'integer',​
'description':​
'The number that identifies the pull request.'​
}​
},​
'required': ['owner', 'repo', 'pull_number']​
}​
})​
def get_pull_request_details(owner: str, repo: str,​
pull_number: int) -> Dict[str, Any]

Get details of a specific pull request.

This function gets details of a specific pull request. It uses the provided

owner, repository name, and pull request number to identify and retrieve

the comprehensive details of the pull request.

Args:
owner (str): The account owner of the repository.

repo (str): The name of the repository.

pull_number (int): The number that identifies the pull request.

Returns:
Dict[str, Any]: A dictionary containing the details of the pull request. Fields include:

id (int): The unique ID of the PR.

node_id (str): The global node ID of the PR.

number (int): The PR number within the repository.

title (str): The title of the PR.

user (Dict[str, Any]): The user who created the PR. Contains fields:

login (str): Username.

id (int): User ID.

node_id (str): Global node ID for the user.

type (str): Type of user (e.g., 'User').

site_admin (bool): Whether the user is a site administrator.

labels (List[Dict[str, Any]]): A list of labels associated with the PR. Each label object in the
list contains fields:

id (int): Label ID.

node_id (str): Global node ID for the label.

name (str): The name of the label.

color (str): The color of the label (hex code).

description (Optional[str]): A short description of the label.

default (bool): Whether this is a default label.

state (str): The state of the PR (e.g., 'open', 'closed', 'merged').

locked (bool): Whether the PR is locked.

assignee (Optional[Dict[str, Any]]): The user assigned to the PR. If present, contains fields:
login (str): Username.

id (int): User ID.

node_id (str): Global node ID for the user.

type (str): Type of user (e.g., 'User').

site_admin (bool): Whether the user is a site administrator.

assignees (List[Dict[str, Any]]): A list of users assigned to the PR. Each user object in the list
contains fields:

login (str): Username.

id (int): User ID.

node_id (str): Global node ID for the user.

type (str): Type of user (e.g., 'User').

site_admin (bool): Whether the user is a site administrator.

milestone (Optional[Dict[str, Any]]): The milestone associated with the PR. If present,
contains fields:

id (int): Milestone ID.

node_id (str): Global node ID for the milestone.

number (int): The number of the milestone.

title (str): The title of the milestone.

description (Optional[str]): A description of the milestone.

creator (Dict[str, Any]): The user who created the milestone. Contains fields:

login (str): Username.

id (int): User ID.

node_id (str): Global node ID for the user.

type (str): Type of user (e.g., 'User').

site_admin (bool): Whether the user is a site administrator.

open_issues (int): The number of open issues in this milestone.

closed_issues (int): The number of closed issues in this milestone.

state (str): The state of the milestone (e.g., 'open', 'closed').

created_at (str): ISO 8601 timestamp of when the milestone was created.

updated_at (str): ISO 8601 timestamp of when the milestone was last updated.

due_on (Optional[str]): ISO 8601 timestamp of the milestone's due date.

closed_at (Optional[str]): ISO 8601 timestamp of when the milestone was closed.

created_at (str): ISO 8601 timestamp of when the PR was created.

updated_at (str): ISO 8601 timestamp of when the PR was last updated.

closed_at (Optional[str]): ISO 8601 timestamp of when the PR was closed.

merged_at (Optional[str]): ISO 8601 timestamp of when the PR was merged.

body (Optional[str]): The content of the PR.

author_association (str): The relationship of the PR author to the repository (e.g., 'OWNER',
'MEMBER', 'COLLABORATOR', 'CONTRIBUTOR', 'FIRST_TIMER',
'FIRST_TIME_CONTRIBUTOR', 'MANNEQUIN', 'NONE').

draft (bool): Whether the PR is a draft.

merged (bool): Whether the PR has been merged.

mergeable (Optional[bool]): Whether the PR can be merged.

rebaseable (Optional[bool]): Whether the PR can be rebased.

mergeable_state (str): The state of mergeability (e.g., 'clean', 'dirty', 'unknown', 'blocked',
'behind', 'unstable').

merged_by (Optional[Dict[str, Any]]): The user who merged the PR. If present, contains
fields:

login (str): Username.

id (int): User ID.

node_id (str): Global node ID for the user.

type (str): Type of user (e.g., 'User').

site_admin (bool): Whether the user is a site administrator.

comments (int): Number of issue-style comments on the PR.

review_comments (int): Number of review comments on the PR.

commits (int): Number of commits in the PR.

additions (int): Number of added lines.

deletions (int): Number of deleted lines.

changed_files (int): Number of files changed.

head (Dict[str, Any]): Details of the head branch. Contains fields:

label (str): A human-readable label for the branch (e.g., 'octocat:new-topic').

ref (str): Branch name.

sha (str): Commit SHA of the head of the branch.

user (Dict[str, Any]): The user who owns the repository of the head branch. Contains fields:

login (str): Username.

id (int): User ID.

node_id (str): Global node ID for the user.

type (str): Type of user (e.g., 'User').

site_admin (bool): Whether the user is a site administrator.

repo (Dict[str, Any]): The repository of the head branch. Contains fields:

id (int): Repository ID.

node_id (str): Global node ID for the repository.

name (str): The name of the repository.

full_name (str): The full name of the repository (owner/name).

private (bool): Whether the repository is private.

owner (Dict[str, Any]): The owner of the repository. Contains fields:

login (str): Username.

id (int): User ID.

node_id (str): Global node ID for the user.

type (str): Type of user (e.g., 'User').

site_admin (bool): Whether the user is a site administrator.

description (Optional[str]): A description of the repository.

fork (bool): Whether the repository is a fork.

created_at (str): ISO 8601 timestamp of when the repository was created.

updated_at (str): ISO 8601 timestamp of when the repository was last updated.

pushed_at (str): ISO 8601 timestamp of the last push.

size (int): The size of the repository in kilobytes.

stargazers_count (int): Number of stargazers.

watchers_count (int): Number of watchers.

language (Optional[str]): The primary language of the repository.

has_issues (bool): Whether issues are enabled.

has_projects (bool): Whether projects are enabled.

has_downloads (bool): Whether downloads are enabled.

has_wiki (bool): Whether the wiki is enabled.

has_pages (bool): Whether GitHub Pages are enabled.

forks_count (int): Number of forks.

archived (bool): Whether the repository is archived.

disabled (bool): Whether the repository is disabled.

open_issues_count (int): Number of open issues.

license (Optional[Dict[str, Any]]): License information. If present, contains fields:

key (str): License key (e.g., 'mit').

name (str): License name (e.g., 'MIT License').

spdx_id (str): SPDX identifier for the license.

allow_forking (bool): Whether forking is allowed.

is_template (bool): Whether this repository is a template repository.

web_commit_signoff_required (bool): Whether web commit signoff is required.

topics (List[str]): A list of topics associated with the repository.

visibility (str): Visibility of the repository (e.g., 'public', 'private', 'internal').

forks (int): Number of forks (alias for forks_count).

open_issues (int): Number of open issues (alias for open_issues_count).

watchers (int): Number of watchers (alias for watchers_count).

default_branch (str): The default branch of the repository.

base (Dict[str, Any]): Details of the base branch. Contains fields:

label (str): A human-readable label for the branch (e.g., 'octocat:main').

ref (str): Branch name.

sha (str): Commit SHA of the head of the base branch.

user (Dict[str, Any]): The user who owns the repository of the base branch. Contains fields:

login (str): Username.

id (int): User ID.

node_id (str): Global node ID for the user.

type (str): Type of user (e.g., 'User').

site_admin (bool): Whether the user is a site administrator.

repo (Dict[str, Any]): The repository of the base branch. Contains fields:

id (int): Repository ID.

node_id (str): Global node ID for the repository.

name (str): The name of the repository.

full_name (str): The full name of the repository (owner/name).

private (bool): Whether the repository is private.

owner (Dict[str, Any]): The owner of the repository. Contains fields:

login (str): Username.

id (int): User ID.

node_id (str): Global node ID for the user.

type (str): Type of user (e.g., 'User').

site_admin (bool): Whether the user is a site administrator.

description (Optional[str]): A description of the repository.

fork (bool): Whether the repository is a fork.

created_at (str): ISO 8601 timestamp of when the repository was created.

updated_at (str): ISO 8601 timestamp of when the repository was last updated.

pushed_at (str): ISO 8601 timestamp of the last push.

size (int): The size of the repository in kilobytes.

stargazers_count (int): Number of stargazers.

watchers_count (int): Number of watchers.

language (Optional[str]): The primary language of the repository.

has_issues (bool): Whether issues are enabled.

has_projects (bool): Whether projects are enabled.

has_downloads (bool): Whether downloads are enabled.

has_wiki (bool): Whether the wiki is enabled.

has_pages (bool): Whether GitHub Pages are enabled.

forks_count (int): Number of forks.

archived (bool): Whether the repository is archived.

disabled (bool): Whether the repository is disabled.

open_issues_count (int): Number of open issues.

license (Optional[Dict[str, Any]]): License information. If present, contains fields:

key (str): License key (e.g., 'mit').

name (str): License name (e.g., 'MIT License').

spdx_id (str): SPDX identifier for the license.

allow_forking (bool): Whether forking is allowed.

is_template (bool): Whether this repository is a template repository.

web_commit_signoff_required (bool): Whether web commit signoff is required.

topics (List[str]): A list of topics associated with the repository.

visibility (str): Visibility of the repository (e.g., 'public', 'private', 'internal').

forks (int): Number of forks (alias for forks_count).

open_issues (int): Number of open issues (alias for open_issues_count).

watchers (int): Number of watchers (alias for watchers_count).

default_branch (str): The default branch of the repository.

Raises:
ValueError: If any of the input parameters are invalid.

NotFoundError: If the repository or pull request does not exist.

get_authenticated_user
@tool_spec(​
spec={​
'name': 'get_authenticated_user',​
'description': """ Get details of the authenticated user.​
​
Gets details of the authenticated user. """,​
'parameters': {​
'type': 'object',​
'properties': {},​
'required': []​
}​
})​
def get_authenticated_user() -> Dict[str, Any]

Get details of the authenticated user.

Gets details of the authenticated user.

Returns:
Dict[str, Any]: A dictionary containing the authenticated user's details with the following
keys:

login (str): The user's username.

id (int): The unique ID of the user.

node_id (str): The global node ID of the user.

name (Optional[str]): The user's full name.

email (Optional[str]): The user's publicly visible email address.

company (Optional[str]): The user's company.

location (Optional[str]): The user's location.

bio (Optional[str]): The user's biography.

public_repos (int): The number of public repositories.

public_gists (int): The number of public gists.

followers (int): The number of followers.

following (int): The number of users the user is following.

created_at (str): ISO 8601 timestamp for when the account was created.

updated_at (str): ISO 8601 timestamp for when the account was last updated.

type (str): The type of account, e.g., 'User' or 'Organization'.

Raises:
AuthenticationError: If the request is not authenticated or if the authenticated user cannot
be found.

search_users
@tool_spec(​
spec={​
'name': 'search_users',​
'description': """ Search for GitHub users.​
​
Find users via various criteria. This method returns up to 100
results per page.​
The query can contain any combination of search keywords and
qualifiers to narrow down the results.​
​
When no sort is specified, results are sorted by best match. """,​
'parameters': {​
'type': 'object',​
'properties': {​
'q': {​
'type':​
'string',​
'description':​
""" The search query string. Can contain any
combination of search keywords and qualifiers.​
For example: `q=tom+repos:>42+followers:>1000`.​
Supported qualifiers:​
- `in:login,name,email`: Restricts search to
specified fields.​
- `repos:n`: Filters by repository count. Can use
`>`, `<`, `>=`, `<=`, and `..` ranges.​
- `followers:n`: Filters by follower count. Can use
`>`, `<`, `>=`, `<=`, and `..` ranges.​
- `created:YYYY-MM-DD`: Filters by creation date. Can
use `>`, `<`, `>=`, `<=`, and `..` ranges.​
- `location:LOCATION`: Filters by location in the
user's profile.​
- `type:user|org`: Restricts search to users or
organizations.​
- `language:LANGUAGE`: Filters by the predominant
language in the user's repositories. """​
},​
'sort': {​
'type':​
'string',​
'description':​
""" The field to sort the search results by. Can be
one of 'followers', 'repositories', 'joined'.​
Defaults to None (best match). """​
},​
'order': {​
'type':​
'string',​
'description':​
"The order of sorting ('asc' or 'desc'). Defaults to
'desc'."​
},​
'page': {​
'type':​
'integer',​
'description':​
'The page number for paginated results. Defaults to
1.'​
},​
'per_page': {​
'type':​
'integer',​
'description':​
'The number of results to return per page (max 100).
Defaults to 30.'​
}​
},​
'required': ['q']​
}​
})​
def search_users(q: str,​
sort: Optional[str] = None,​
order: Optional[str] = "desc",​
 page: Optional[int] = 1,​
per_page: Optional[int] = 30) -> Dict[str, Any]

Search for GitHub users.

Find users via various criteria. This method returns up to 100 results per page.

The query can contain any combination of search keywords and qualifiers to narrow down
the results.

When no sort is specified, results are sorted by best match.

Args:
q (str): The search query string. Can contain any combination of search keywords and
qualifiers.

For example: `q=tom+repos:>42+followers:>1000`.

Supported qualifiers:

• `in:login,name,email`: Restricts search to specified fields.

• `repos:n`: Filters by repository count. Can use `>`, `<`, `>=`, `<=`, and `..`
ranges.

• `followers:n`: Filters by follower count. Can use `>`, `<`, `>=`, `<=`, and `..`
ranges.

• `created:YYYY-MM-DD`: Filters by creation date. Can use `>`, `<`, `>=`, `<=`,
and `..` ranges.

• `location:LOCATION`: Filters by location in the user's profile.

• `type:user|org`: Restricts search to users or organizations.

• `language:LANGUAGE`: Filters by the predominant language in the user's

repositories.

sort (Optional[str]): The field to sort the search results by. Can be one of 'followers',
'repositories', 'joined'.

Defaults to None (best match).

order (Optional[str]): The order of sorting ('asc' or 'desc'). Defaults to 'desc'.

page (Optional[int]): The page number for paginated results. Defaults to 1.

per_page (Optional[int]): The number of results to return per page (max 100). Defaults to
30.
Returns:
Dict[str, Any]: A dictionary containing user search results with the following keys:

total_count (int): The total number of users found.

incomplete_results (bool): Indicates if the search timed out before finding all results.

items (List[Dict[str, Any]]): A list of user objects matching the search criteria. Each user
object in the list has the following fields:

login (str): The user's username.

id (int): The unique ID of the user.

node_id (str): The global node ID of the user.

type (str): The type of account, e.g., 'User' or 'Organization'.

score (float): The search score associated with the user.

Raises:
InvalidInputError: If the search query 'q' is missing or invalid, or if pagination parameters
are incorrect.

RateLimitError: If the API rate limit is exceeded.

search_repositories
@tool_spec(​
spec={​
'name': 'search_repositories',​
'description': """ Search for GitHub repositories.​
​
Find repositories via various criteria. This method returns up to
100 results per page.​
The query can contain any combination of search keywords and
qualifiers to narrow down the results.​
​
When no sort is specified, results are sorted by best match. """,​
'parameters': {​
'type': 'object',​
'properties': {​
'query': {​
'type':​
'string',​
'description':​
""" The search query string. Can contain any
combination of search keywords and qualifiers.​
For example:
`q=tetris+language:assembly+fork:true+stars:>=100`.​
 Supported qualifiers:​
- `in:name,description`​
- `size:>=N`, `size:N..M`​
- `forks:N`, `stars:N`, `watchers:N` (with ranges)​
- `user:USERNAME`, `org:USERNAME`​
- `language:LANGUAGE`​
- `created:DATE`, `pushed:DATE`, `updated:DATE` (with
ranges)​
- `is:public`, `is:private`, `is:archived`,
`is:template`​
- `fork:true`, `fork:only` """​
},​
'sort': {​
'type':​
'string',​
'description':​
'The field to sort by. Can be `stars`, `forks`,
`updated`. Defaults to None.'​
},​
'order': {​
'type':​
'string',​
'description':​
'The direction to sort. Can be `asc` or `desc`.
Defaults to `desc`.'​
},​
'page': {​
'type':​
'integer',​
'description':​
'Page number of the results to fetch. Defaults to 1.'​
},​
'per_page': {​
'type':​
'integer',​
'description':​
'The number of results per page (max 100). Defaults
to 30.'​
}​
},​
'required': ['query']​
}​
})​
def search_repositories(query: str,​
sort: Optional[str] = None,​
order: Optional[str] = "desc",​
page: Optional[int] = 1,​
per_page: Optional[int] = 30) -> Dict[str, Any]
Search for GitHub repositories.

Find repositories via various criteria. This method returns up to 100 results per page.

The query can contain any combination of search keywords and qualifiers to narrow down
the results.

When no sort is specified, results are sorted by best match.

Args:
query (str): The search query string. Can contain any combination of search keywords and
qualifiers.

For example: `q=tetris+language:assembly+fork:true+stars:>=100`.

Supported qualifiers:

• `in:name,description`

• `size:>=N`, `size:N..M`

• `forks:N`, `stars:N`, `watchers:N` (with ranges)

• `user:USERNAME`, `org:USERNAME`

• `language:LANGUAGE`

• `created:DATE`, `pushed:DATE`, `updated:DATE` (with ranges)

• `is:public`, `is:private`, `is:archived`, `is:template`

• `fork:true`, `fork:only`

sort (Optional[str]): The field to sort by. Can be `stars`, `forks`, `updated`. Defaults to None.

order (Optional[str]): The direction to sort. Can be `asc` or `desc`. Defaults to `desc`.

page (Optional[int]): Page number of the results to fetch. Defaults to 1.

per_page (Optional[int]): The number of results per page (max 100). Defaults to 30.

Returns:
Dict[str, Any]: A dictionary containing a `search_results` object with the repository search
results.

The `search_results` object has the following keys:

• total_count (int): The total number of repositories matching the search

query.
• incomplete_results (bool): Indicates whether the search timed out before
all results could be gathered.

• items (List[Dict[str, Any]]): A list of repository objects. Each repository

object has the following structure:

• id (int): The unique identifier for the repository.

• node_id (str): A global identifier for the repository.

• name (str): The name of the repository.

• full_name (str): The full name of the repository, in

'owner_login/repository_name' format.

• private (bool): Indicates whether the repository is private.

• owner (Dict[str, Any]): An object describing the owner of the

repository, containing:

• login (str): The owner's username.

• id (int): The unique identifier for the owner.

• node_id (str): A global identifier for the owner.

• type (str): The type of owner (e.g., 'User', 'Organization').

• site_admin (bool): Indicates if the owner is a site

administrator.

• description (Optional[str]): A description of the repository. Null if

not provided.

• fork (bool): Indicates whether the repository is a fork of another

repository.

• created_at (str): The timestamp (ISO 8601 format) for when the
repository was created.

• updated_at (str): The timestamp (ISO 8601 format) for when the
repository was last updated.

• pushed_at (str): The timestamp (ISO 8601 format) for when the
repository was last pushed to.

• stargazers_count (int): The number of users who have starred the

repository.

• watchers_count (int): The number of users watching the repository.

 • forks_count (int): The number of times the repository has been
forked.

• open_issues_count (int): The number of open issues in the

repository.

• language (Optional[str]): The primary programming language of

the repository. Null if not detected.

• score (float): The relevance score assigned to the repository by the

search algorithm.

Raises:
InvalidInputError: If the query is invalid or pagination parameters are incorrect.

list_repository_commits
@tool_spec(​
spec={​
'name': 'list_repository_commits',​
'description': """ Get a list of commits of a branch in a
repository.​
​
This function gets a list of commits of a branch in a repository.
""",​
'parameters': {​
'type': 'object',​
'properties': {​
'owner': {​
'type': 'string',​
'description': 'The owner of the repository.'​
},​
'repo': {​
'type': 'string',​
'description': 'The name of the repository.'​
},​
'sha': {​
'type':​
'string',​
'description':​
'The commit SHA or branch name to list commits from.
Defaults to None.'​
},​
'path': {​
'type':​
'string',​
'description':​
'Only commits containing this file path will be
returned. Defaults to None.'​
},​
 'page': {​
'type':​
'integer',​
'description':​
'Page number of the results to fetch for pagination.
Defaults to 1.'​
},​
'per_page': {​
'type':​
'integer',​
'description':​
'The number of results per page for pagination.
Defaults to 30.'​
}​
},​
'required': ['owner', 'repo']​
}​
})​
def list_repository_commits(​
owner: str,​
repo: str,​
sha: Optional[str] = None,​
path: Optional[str] = None,​
page: Optional[int] = 1,​
per_page: Optional[int] = 30) -> List[Dict[str, Any]]

Get a list of commits of a branch in a repository.

This function gets a list of commits of a branch in a repository.

Args:
owner (str): The owner of the repository.

repo (str): The name of the repository.

sha (Optional[str]): The commit SHA or branch name to list commits from. Defaults to None.

path (Optional[str]): Only commits containing this file path will be returned. Defaults to
None.

page (Optional[int]): Page number of the results to fetch for pagination. Defaults to 1.

per_page (Optional[int]): The number of results per page for pagination. Defaults to 30.

Returns:
List[Dict[str, Any]]: A list of commit objects. Each dictionary in this list

represents a commit and has the following keys:

sha (str): The SHA (Secure Hash Algorithm) identifier of the commit.
node_id (str): The global node ID of the commit.

commit (Dict[str, Any]): Core commit information. Contains the following fields:

author (Dict[str, Any]): Details of the original author of the commit

(not necessarily the committer). Contains the following fields:

name (str): The name of the git author.

email (str): The email of the git author.

date (str): The timestamp (ISO 8601 format) when this commit

was authored.

committer (Dict[str, Any]): Details of the user who committed the

changes. Contains the following fields:

name (str): The name of the git committer.

email (str): The email of the git committer.

date (str): The timestamp (ISO 8601 format) when this commit

was committed.

message (str): The commit message.

tree (Dict[str, Any]): Details of the tree object associated with this

commit. Contains the following fields:

sha (str): The SHA of the tree object.

comment_count (int): The number of comments on the commit.

author (Optional[Dict[str, Any]]): The GitHub user account that authored the

commit, if linked to a GitHub account. This can be null if the

author is not a GitHub user or if the commit author information is

forged. Contains the following fields:

login (str): The GitHub username of the author.

id (int): The unique GitHub ID of the author.

node_id (str): The global node ID of the author.

gravatar_id (str): The Gravatar ID for the user (note: this is an

ID, not a URL).

type (str): The type of GitHub account (e.g., 'User', 'Bot').

site_admin (bool): Indicates if the user is a site administrator

on GitHub.

committer (Optional[Dict[str, Any]]): The GitHub user account that committed

the changes, if linked to a GitHub account. This can be null if the

committer is not a GitHub user or if the committer information is

forged. Contains the following fields:

login (str): The GitHub username of the committer.

id (int): The unique GitHub ID of the committer.

node_id (str): The global node ID of the committer.

gravatar_id (str): The Gravatar ID for the user (note: this is an

ID, not a URL).

type (str): The type of GitHub account (e.g., 'User', 'Bot').

site_admin (bool): Indicates if the user is a site administrator

on GitHub.

parents (List[Dict[str, Any]]): A list of parent commit objects. Each parent

object (a dictionary) in this list contains:

sha (str): The SHA of a parent commit.

node_id (str): The global node ID of the parent commit.

Raises:
ValidationError: If input parameters are invalid (empty strings, invalid formats,

out of range values, or type mismatches).

NotFoundError: If the repository doesn't exist, specified SHA/branch isn't found,

path doesn't exist, default branch is not configured, or the starting

commit SHA cannot be determined.

get_repository_commit_details
@tool_spec(​
spec={​
'name': 'get_repository_commit_details',​
'description': """ Get details for a commit from a repository.​
​
This function gets details for a commit from a repository. The
`page` and​
`per_page` parameters can be used to paginate the list of files
affected​
by the commit, which is part of the returned details. """,​
'parameters': {​
'type': 'object',​
'properties': {​
'owner': {​
'type': 'string',​
'description': 'The owner of the repository.'​
},​
'repo': {​
'type': 'string',​
'description': 'The name of the repository.'​
},​
'sha': {​
'type': 'string',​
'description': 'The SHA of the commit to retrieve.'​
},​
'page': {​
'type':​
'integer',​
'description':​
'Page number for paginating the list of files
affected by the commit. Defaults to None.'​
},​
'per_page': {​
'type':​
'integer',​
'description':​
'The number of files to return per page when
paginating. Defaults to None.'​
}​
},​
'required': ['owner', 'repo', 'sha']​
}​
})​
def get_repository_commit_details(​
owner: str,​
repo: str,​
 sha: str,​
page: Optional[int] = None,​
per_page: Optional[int] = None) -> Dict[str, Any]

Get details for a commit from a repository.

This function gets details for a commit from a repository. The `page` and

`per_page` parameters can be used to paginate the list of files affected

by the commit, which is part of the returned details.

Args:
owner (str): The owner of the repository.

repo (str): The name of the repository.

sha (str): The SHA of the commit to retrieve.

page (Optional[int]): Page number for paginating the list of files affected by the commit.
Defaults to None.

per_page (Optional[int]): The number of files to return per page when paginating. Defaults
to None.

Returns:
Dict[str, Any]: A dictionary containing details for a specific commit. It includes the following
keys:

sha (str): The SHA of the commit.

node_id (str): The global node ID of the commit.

commit (Dict[str, Any]): Formatted commit details, containing:

author (Dict[str, Any]): Details of the original author of the commit:

name (str): Author's name.

email (str): Author's email address.

date (str): Timestamp of when the commit was authored (ISO 8601 format).

committer (Dict[str, Any]): Details of the person who committed the changes:

name (str): Committer's name.

email (str): Committer's email address.

date (str): Timestamp of when the commit was made (ISO 8601 format).
message (str): The commit message.

tree (Dict[str, Any]): Information about the commit's tree:

sha (str): The SHA of the tree object.

author (Optional[Dict[str, Any]]): The GitHub user who authored the commit (if linked to a
GitHub account).

If present, contains:

login (str): The GitHub login of the author.

id (int): The GitHub ID of the author.

committer (Optional[Dict[str, Any]]): The GitHub user who committed the changes (if linked
to a GitHub account).

If present, contains:

login (str): The GitHub login of the committer.

id (int): The GitHub ID of the committer.

parents (List[Dict[str, Any]]): A list of parent commit objects. Each object in the list contains:

sha (str): The SHA of the parent commit.

stats (Optional[Dict[str, Any]]): Commit statistics. If present, contains:

total (int): Total number of changes (additions + deletions).

additions (int): Number of lines added.

deletions (int): Number of lines deleted.

files (Optional[List[Dict[str, Any]]]): A list of files affected by this commit. This list may be

paginated if 'page' and 'per_page' parameters are used in the request. Each file

object in the list contains:

sha (str): Blob SHA of the file.

filename (str): Name and path of the file.

status (str): Status of the file in this commit (e.g., 'added', 'modified', 'removed', 'renamed').

additions (int): Number of additions made to this file.

deletions (int): Number of deletions made from this file.

changes (int): Total number of changes in this file.

patch (Optional[str]): The patch data (diff) for the file, detailing the changes.

Raises:
ValidationError: If input parameters are invalid (invalid types, negative values for
page/per_page).

NotFoundError: If the repository or commit SHA does not exist.

create_repository_branch
@tool_spec(​
spec={​
'name': 'create_repository_branch',​
'description': """ Create a new branch.​
​
This function establishes a new branch of development within the
repository. """,​
'parameters': {​
'type': 'object',​
'properties': {​
'owner': {​
'type': 'string',​
'description': 'The account owner of the repository.'​
},​
'repo': {​
'type': 'string',​
'description': 'The name of the repository.'​
},​
'branch': {​
'type': 'string',​
'description': 'The name of the new branch to
create.'​
},​
'sha': {​
'type':​
'string',​
'description':​
'The SHA of the commit from which the new branch will
be created.'​
}​
},​
'required': ['owner', 'repo', 'branch', 'sha']​
}​
})​
def create_repository_branch(owner: str, repo: str, branch: str,​
sha: str) -> Dict[str, Any]

Create a new branch.

This function establishes a new branch of development within the repository.

Args:
owner (str): The account owner of the repository.

repo (str): The name of the repository.

branch (str): The name of the new branch to create.

sha (str): The SHA of the commit from which the new branch will be created.

Returns:
Dict[str, Any]: A dictionary containing branch creation details with the following keys:

ref (str): The full Git ref (e.g., 'refs/heads/new-branch').

node_id (str): The global node ID for the ref.

object (Dict[str, Any]): Details of the Git object this ref points to. This dictionary contains the
following keys:

type (str): The type of the Git object, usually 'commit'.

sha (str): The SHA of the commit the new branch points to.

Raises:
NotFoundError: If the repository or the source 'sha' does not exist.

UnprocessableEntityError: If the branch already exists, if the 'sha' is not a valid commit SHA,

if the branch name is invalid, or if required fields (owner, repo, branch, sha)

are missing or have invalid formats.

create_or_update_repository_file
@tool_spec(​
spec={​
'name': 'create_or_update_repository_file',​
'description': """ Create or update a single file in a
repository.​
​
This function creates a new file or updates an existing file at a
specified​
path within a given repository. It requires the repository
owner's identifier,​
the repository name, the file's path, a commit message, and the
file's​
content. Optional parameters include the branch name and, for
file updates,​
the SHA of the existing file blob to ensure the correct file
version is modified. """,​
'parameters': {​
'type': 'object',​
'properties': {​
'owner': {​
'type':​
'string',​
'description':​
'The account owner of the repository (e.g., username
or organization name).'​
},​
'repo': {​
'type': 'string',​
'description': 'The name of the repository.'​
},​
'path': {​
'type': 'string',​
'description': 'The path to the file in the
repository.'​
},​
'message': {​
'type': 'string',​
'description': 'The commit message.'​
},​
'content': {​
'type': 'string',​
'description': 'The new file content, base64
encoded.'​
},​
'branch': {​
'type':​
'string',​
'description':​
""" The branch name. If not provided, the operation​
typically targets the repository's default branch.
Defaults to None. """​
},​
'sha': {​
'type':​
'string',​
'description':​
""" The blob SHA of the file being replaced. This is​
required if updating an existing file and is used to
prevent conflicts​
by ensuring the file has not changed since the SHA
was obtained.​
Defaults to None. """​
}​
},​
 'required': ['owner', 'repo', 'path', 'message', 'content']​
}​
})​
def create_or_update_repository_file(​
owner: str,​
repo: str,​
path: str,​
message: str,​
content: str,​
branch: Optional[str] = None,​
sha: Optional[str] = None) -> Dict[str, Any]

Create or update a single file in a repository.

This function creates a new file or updates an existing file at a specified

path within a given repository. It requires the repository owner's identifier,

the repository name, the file's path, a commit message, and the file's

content. Optional parameters include the branch name and, for file updates,

the SHA of the existing file blob to ensure the correct file version is modified.

Args:
owner (str): The account owner of the repository (e.g., username or organization name).

repo (str): The name of the repository.

path (str): The path to the file in the repository.

message (str): The commit message.

content (str): The new file content, base64 encoded.

branch (Optional[str]): The branch name. If not provided, the operation

typically targets the repository's default branch. Defaults to None.

sha (Optional[str]): The blob SHA of the file being replaced. This is

required if updating an existing file and is used to prevent conflicts

by ensuring the file has not changed since the SHA was obtained.

Defaults to None.

Returns:
Dict[str, Any]: A dictionary containing details about the commit and the file.

It has the following top-level keys:

content (Dict[str, Any]): Details of the created/updated file. This dictionary contains:

name (str): The name of the file.

path (str): The path of the file in the repository.

sha (str): The SHA (blob) of the file content.

size (int): The size of the file in bytes.

type (str): The type of the object, typically 'file'.

commit (Dict[str, Any]): Details of the commit that created/updated the file. This dictionary
contains:

sha (str): The SHA of the commit.

message (str): The commit message.

author (Dict[str, Any]): The author of the commit. This dictionary contains:

name (str): The name of the author.

email (str): The email address of the author.

date (str): The timestamp of the authorship, in ISO 8601 format (e.g.,
'YYYY-MM-DDTHH:MM:SSZ').

committer (Dict[str, Any]): The committer of the commit. This dictionary contains:

name (str): The name of the committer.

email (str): The email address of the committer.

date (str): The timestamp of the commit, in ISO 8601 format (e.g.,
'YYYY-MM-DDTHH:MM:SSZ').

Raises:
NotFoundError: If the repository or branch (if specified) does not exist.

ValidationError: If required fields (path, message, content) are missing

or if content is not base64 encoded.

ConflictError: If updating a file and the provided 'sha' does not match

the latest file SHA (blob SHA).

ForbiddenError: If the user does not have write access to the repository

(e.g., repository is archived or branch is protected).

create_repository
@tool_spec(​
spec={​
'name': 'create_repository',​
'description': """ Create a new GitHub repository.​
​
Creates a new GitHub repository. The user specifies the name for
the​
repository and can optionally provide a description, set its
visibility,​
and choose to auto-initialize it.​
​
Default Repository Settings:​
The following features are enabled by default for new
repositories:​
- has_issues: True (Issues are enabled)​
- has_projects: True (Projects are enabled)​
- has_downloads: True (Downloads are enabled)​
- has_wiki: True (Wiki is enabled)​
- has_pages: False (GitHub Pages are disabled)​
- allow_forking: True (Repository can be forked)​
- archived: False (Repository is not archived)​
- disabled: False (Repository is not disabled)​
- is_template: False (Repository is not a template)​
- web_commit_signoff_required: False (Commit signoff not
required)​
- visibility: "public" or "private" (based on private
parameter) """,​
'parameters': {​
'type': 'object',​
'properties': {​
'name': {​
'type': 'string',​
'description': 'The name for the new repository.'​
},​
'description': {​
'type':​
'string',​
'description':​
'An optional description for the repository. Defaults
to None.'​
},​
'private': {​
'type':​
'boolean',​
'description':​
'If True, the repository will be private. Defaults to
False.'​
},​
 'auto_init': {​
'type':​
'boolean',​
'description':​
'If True, creates an initial commit, potentially with
a README. Defaults to False.'​
}​
},​
'required': ['name']​
}​
})​
def create_repository(name: str,​
description: Optional[str] = None,​
private: Optional[bool] = False,​
auto_init: Optional[bool] = False) -> Dict[str,
Any]

Create a new GitHub repository.

Creates a new GitHub repository. The user specifies the name for the

repository and can optionally provide a description, set its visibility,

and choose to auto-initialize it.

Default Repository Settings:

The following features are enabled by default for new repositories:

• has_issues: True (Issues are enabled)

• has_projects: True (Projects are enabled)

• has_downloads: True (Downloads are enabled)

• has_wiki: True (Wiki is enabled)

• has_pages: False (GitHub Pages are disabled)

• allow_forking: True (Repository can be forked)

• archived: False (Repository is not archived)

• disabled: False (Repository is not disabled)

• is_template: False (Repository is not a template)

• web_commit_signoff_required: False (Commit signoff not required)

• visibility: "public" or "private" (based on private parameter)

Args:
name (str): The name for the new repository.

description (Optional[str]): An optional description for the repository. Defaults to None.

private (Optional[bool]): If True, the repository will be private. Defaults to False.

auto_init (Optional[bool]): If True, creates an initial commit, potentially with a README.

Defaults to False.

Returns:
Dict[str, Any]: A dictionary containing the details of the newly created repository with the
following keys:

id (int): Unique identifier for the repository.

node_id (str): A globally unique identifier for the repository node.

name (str): The name of the repository.

full_name (str): The full name of the repository, including the owner (e.g., 'owner/repo').

private (bool): Indicates whether the repository is private.

owner (Dict[str, Any]): Details of the repository owner. Key non-URL fields include:

login (str): the owner's username.

id (int): the owner's unique ID.

type (str): e.g., 'User' or 'Organization'.

description (str): A short description of the repository.

fork (bool): Indicates if the repository is a fork. This will be false for newly created
repositories.

created_at (str): The ISO 8601 timestamp for when the repository was created.

updated_at (str): The ISO 8601 timestamp for when the repository was last updated.

pushed_at (str): The ISO 8601 timestamp for when the repository was last pushed to.

default_branch (str): The name of the default branch (e.g., 'main'). This is typically present if
'auto_init' was true during creation.

Raises:
ValidationError: If required inputs are missing (e.g., repository name) or if inputs are
malformed (e.g., invalid characters in the name).
UnprocessableEntityError: If the repository cannot be created due to semantic reasons, such
as the repository name already existing for the user/organization, or other server-side
validation failures not related to input format.

ForbiddenError: If the authenticated user does not have the necessary permissions to create
a repository (e.g., insufficient rights for an organization, or account restriction).

push_repository_files
@tool_spec(​
spec={​
'name': 'push_repository_files',​
'description': """ Push multiple files in a single commit.​
​
This function pushes multiple files in a single commit. It uses
the provided​
repository owner's username, repository name, target branch name,
a list of​
files (each defined by its path and content), and a commit
message to​
perform the operation. """,​
'parameters': {​
'type': 'object',​
'properties': {​
'owner': {​
'type':​
'string',​
'description':​
'The username of the account that owns the
repository.'​
},​
'repo': {​
'type': 'string',​
'description': 'The name of the repository.'​
},​
'branch': {​
'type': 'string',​
'description':​
'The name of the branch to push the files to.'​
},​
'files': {​
'type': 'array',​
'description':​
""" A list of dictionaries, where each dictionary​
represents a file to be pushed. Each dictionary must
contain the​
following keys: """,​
'items': {​
'type': 'object',​
'properties': {​
 'path': {​
'type':​
'string',​
'description':​
'The full path of the file within the
repository.'​
},​
'content': {​
'type': 'string',​
'description': 'The content of the file.'​
}​
},​
'required': ['path', 'content']​
}​
},​
'message': {​
'type': 'string',​
'description': 'The commit message for the push
operation.'​
},​
'author_date': {​
'type':​
'string',​
'description':​
""" Custom author date in ISO 8601 format
(YYYY-MM-DDTHH:MM:SSZ).​
If not provided, current date will be used. Defaults
to None. """​
},​
'committer_date': {​
'type':​
'string',​
'description':​
""" Custom committer date in ISO 8601 format
(YYYY-MM-DDTHH:MM:SSZ).​
If not provided, current date will be used. Defaults
to None. """​
}​
},​
'required': ['owner', 'repo', 'branch', 'files', 'message']​
}​
})​
def push_repository_files(​
owner: str,​
repo: str,​
branch: str,​
files: List[Dict[str, str]],​
message: str,​
 author_date: Optional[str] = None,​
committer_date: Optional[str] = None) -> Dict[str, Any]

Push multiple files in a single commit.

This function pushes multiple files in a single commit. It uses the provided

repository owner's username, repository name, target branch name, a list of

files (each defined by its path and content), and a commit message to

perform the operation.

Args:
owner (str): The username of the account that owns the repository.

repo (str): The name of the repository.

branch (str): The name of the branch to push the files to.

files (List[Dict[str, str]]): A list of dictionaries, where each dictionary

represents a file to be pushed. Each dictionary must contain the

following keys:

path (str): The full path of the file within the repository.

content (str): The content of the file.

message (str): The commit message for the push operation.

author_date (Optional[str]): Custom author date in ISO 8601 format

(YYYY-MM-DDTHH:MM:SSZ).

If not provided, current date will be used. Defaults to None.

committer_date (Optional[str]): Custom committer date in ISO 8601 format

(YYYY-MM-DDTHH:MM:SSZ).

If not provided, current date will be used. Defaults to None.

Returns:
Dict[str, Any]: Details of the successful push operation, including commit

information. It contains the following fields:

commit_sha (str): The SHA of the new commit created.

tree_sha (str): The SHA of the new tree object representing the repository state.
message (str): A confirmation message regarding the push.

Raises:
NotFoundError: If the repository or branch does not exist, or if the

owner (acting as committer) is not found in the Users table.

ValidationError: If 'files' list is empty, file structure is invalid

(e.g., missing 'path' or 'content' in a file dictionary),

or message is missing.

ConflictError: If the push cannot be fast-forwarded or if there are

conflicts with recent changes on the branch.

list_repository_branches
@tool_spec(​
spec={​
'name': 'list_repository_branches',​
'description': """ List branches in a GitHub repository.​
​
Lists branches in a GitHub repository, sorted by name. This
function allows for pagination​
of the results. """,​
'parameters': {​
'type': 'object',​
'properties': {​
'owner': {​
'type':​
'string',​
'description':​
'The owner of the repository. Must not be empty.'​
},​
'repo': {​
'type': 'string',​
'description':​
'The name of the repository. Must not be empty.'​
},​
'page': {​
'type':​
'integer',​
'description':​
""" The page number of the results to fetch. Defaults
to 1.​
Must be a positive integer if provided. """​
},​
'per_page': {​
'type':​
 'integer',​
'description':​
""" The number of results per page. Defaults to 30.​
Must be a positive integer if provided. """​
}​
},​
'required': ['owner', 'repo']​
}​
})​
def list_repository_branches(​
owner: str,​
repo: str,​
page: Optional[int] = 1,​
per_page: Optional[int] = 30) -> List[Dict[str, Any]]

List branches in a GitHub repository.

Lists branches in a GitHub repository, sorted by name. This function allows for pagination

of the results.

Args:
owner (str): The owner of the repository. Must not be empty.

repo (str): The name of the repository. Must not be empty.

page (Optional[int]): The page number of the results to fetch. Defaults to 1.

Must be a positive integer if provided.

per_page (Optional[int]): The number of results per page. Defaults to 30.

Must be a positive integer if provided.

Returns:
List[Dict[str, Any]]: A list of branch objects from the repository, sorted by name.

Each dictionary in the list represents a branch object and has the following fields:

name (str): The name of the branch.

commit (Dict[str, Any]): A dictionary representing the latest commit on this

branch. This dictionary contains at least the following field:

sha (str): The SHA identifier of the commit.

protected (bool): A boolean indicating if the branch is protected.

Raises:
NotFoundError: If the repository does not exist.

ValidationError: If invalid inputs are provided.

fork_repository
@tool_spec(​
spec={​
'name': 'fork_repository',​
'description': """ Fork a repository.​
​
Creates a fork for the authenticated user. The user should have ​
`Administration` repository permissions (write) to set up and
configure the new repository (users fork) under the users account.​
`Contents` repository permissions (read) to read the `Contents`
of the original repository to get all the data. """,​
'parameters': {​
'type': 'object',​
'properties': {​
'owner': {​
'type':​
'string',​
'description':​
""" The account owner of the repository. The name is
not case sensitive.​
Must be a non-empty string without whitespace
characters. Maximum 39 characters. """​
},​
'repo': {​
'type':​
'string',​
'description':​
""" The name of the repository without the `.git`
extension. The name is not case sensitive.​
Must be a non-empty string without whitespace
characters. Maximum 100 characters. """​
},​
'organization': {​
'type':​
'string',​
'description':​
""" Optional parameter to specify the organization
name if forking into an organization. Defaults to None.​
If provided, must be a non-empty string without
whitespace characters. Maximum 39 characters. """​
}​
},​
'required': ['owner', 'repo']​
}​
 })​
def fork_repository(owner: str,​
repo: str,​
organization: Optional[str] = None) -> Dict[str, Any]

Fork a repository.

Creates a fork for the authenticated user. The user should have

`Administration` repository permissions (write) to set up and configure the new repository
(users fork) under the users account.

`Contents` repository permissions (read) to read the `Contents` of the original repository to
get all the data.

Args:
owner (str): The account owner of the repository. The name is not case sensitive.

Must be a non-empty string without whitespace characters. Maximum 39 characters.

repo (str): The name of the repository without the `.git` extension. The name is not case
sensitive.

Must be a non-empty string without whitespace characters. Maximum 100 characters.

organization (Optional[str]): Optional parameter to specify the organization name if forking

into an organization. Defaults to None.

If provided, must be a non-empty string without whitespace characters. Maximum 39

characters.

Returns:
Dict[str, Any]: A dictionary containing the details of the newly forked repository. The
structure includes the following fields:

id (int): The unique identifier for the repository.

name (str): The name of the repository.

full_name (str): The full name of the repository, in the format

'owner_login/repository_name'.

owner (Dict[str, Any]): An object describing the owner of the forked repository. It includes
the following sub-fields:

login (str): The login name of the owner.

id (int): The unique identifier of the owner.

type (str): The type of owner (e.g., 'User', 'Organization').

private (bool): True if the repository is private, false otherwise.

description (Optional[str]): A short description of the repository.

fork (bool): True, indicating that this repository is a fork.

Raises:
ValidationError: If input validation fails, including:

• Parameters are not of the expected string type

• Parameters are empty or contain only whitespace characters

• Parameters contain invalid whitespace characters (spaces)

• Parameters exceed maximum length limits (owner/organization: 39 chars,

repo: 100 chars)

RuntimeError: If the authenticated user cannot be resolved from the DB.

NotFoundError: If the source repository does not exist or target organization does not exist.

UnprocessableEntityError: If the repository has already been forked by the

user/organization, or other fork restrictions apply.

ForbiddenError: If the user does not have permission to read the source repository,

if forking is disabled on the source, or if the user cannot create

repositories in the target organization.

get_repository_file_contents
@tool_spec(​
spec={​
'name': 'get_repository_file_contents',​
'description': """ Get contents of a file or directory.​
​
This function retrieves the content of a specified file or
directory within a​
repository. The nature of the returned data depends on whether
the specified​
path points to a file or a directory. """,​
'parameters': {​
'type': 'object',​
'properties': {​
'owner': {​
'type': 'string',​
'description': 'The owner of the repository.'​
},​
'repo': {​
 'type': 'string',​
'description': 'The name of the repository.'​
},​
'path': {​
'type':​
'string',​
'description':​
'The path to the file or directory within the
repository.'​
},​
'ref': {​
'type':​
'string',​
'description':​
""" An optional Git reference (e.g., a branch name,​
tag, or commit SHA) specifying the version of the
content to retrieve.​
Defaults to None. """​
}​
},​
'required': ['owner', 'repo', 'path']​
}​
})​
def get_repository_file_contents(​
owner: str,​
repo: str,​
path: str,​
ref: Optional[str] = None​
) -> Union[Dict[str, Any], List[Dict[str, Any]]]

Get contents of a file or directory.

This function retrieves the content of a specified file or directory within a

repository. The nature of the returned data depends on whether the specified

path points to a file or a directory.

Args:
owner (str): The owner of the repository.

repo (str): The name of the repository.

path (str): The path to the file or directory within the repository.

ref (Optional[str]): An optional Git reference (e.g., a branch name,

tag, or commit SHA) specifying the version of the content to retrieve.

Defaults to None.
Returns:
Union[Dict[str, Any], List[Dict[str, Any]]]: The content of the specified path.

If the path points to a file, this will be a dictionary containing file

details with the following keys:

type (str): The type of content, typically 'file'.

encoding (str): The encoding of the file content, e.g., 'base64'.

size (int): The size of the file in bytes.

name (str): The name of the file.

path (str): The path of the file within the repository.

content (str): The content of the file, typically base64 encoded.

sha (str): The Git blob SHA of the file.

If the path points to a directory, this will be a list of dictionaries.

Each dictionary in the list represents a file or directory entry and

contains the following keys:

type (str): The type of item, either 'file' or 'dir'.

size (int): The size of the item in bytes. For directories, this may

represent the size of the tree object or be 0.

name (str): The name of the file or directory.

path (str): The path of the file or directory within the repository.

sha (str): The Git blob SHA (for files) or tree SHA (for directories).

Raises:
ValidationError: If owner, repo, or path are empty.

NotFoundError: If the repository, branch/ref, or path does not exist.

search_repository_code
@tool_spec(​
spec={​
'name': 'search_repository_code',​
'description': """ Search for code within repositories.​
​
Searches for query terms inside of files. This method returns up
to 100 results per page.​
The query can contain any combination of search keywords and
qualifiers.​
​
Note: Due to the complexity of searching code, there are a few
restrictions:​
- Only the default branch is considered. In most cases, this will
be the master branch.​
- Only files smaller than 384 KB are searchable.​
- You must always include at least one search term when searching
source code.​
For example, searching for language:go is not valid, while
amazing language:go is. """,​
'parameters': {​
'type': 'object',​
'properties': {​
'query': {​
'type':​
'string',​
'description':​
""" The search query string. Can contain any
combination of search keywords and qualifiers.​
Examples:​
- `"addClass in:file language:js
repo:jquery/jquery"`: Find files containing 'addClass' in the
jquery/jquery repository​
- `"repo:octocat/Spoon-Knife css"`: Find instances of
'css' in the octocat/Spoon-Knife repository​
- `"shogun user:heroku language:ruby"`: Find 'shogun'
in Ruby files from heroku's repositories​
- `"function size:>10000 language:python"`: Find
Python files containing 'function' larger than 10 KB​
​
Supported qualifiers:​
- `in:file,path`: Search in file contents and/or file
paths. If not specified, searches in both.​
- `language:LANGUAGE`: Filter by programming language
(based on file extension).​
Supported languages: javascript (js), python
(py), ruby (rb), go, java, c++ (cpp),​
typescript (ts), php, c# (cs), html, css, shell
(sh), markdown (md).​
- `repo:owner/repository`: Restrict search to a
specific repository.​
- `user:USERNAME`, `org:USERNAME`: Search within a
user's or organization's repositories.​
- `size:n`: Filter by file size (in bytes). Can use
`>`, `<`, `>=`, `<=`, and `..` ranges.​
- `path:PATH`: Filter by file path.​
 - `extension:EXTENSION`: Filter by file extension.​
- `is:public`, `is:private`: Filter by repository
visibility.​
- `fork:true`, `fork:only`: Include forked
repositories in the search. """​
},​
'sort': {​
'type':​
'string',​
'description':​
""" The field to sort by. Can be 'indexed' or 'best
match'.​
Defaults to 'best match'. """​
},​
'order': {​
'type':​
'string',​
'description':​
"The direction to sort. Can be 'asc' or 'desc'.
Defaults to 'desc'."​
},​
'page': {​
'type':​
'integer',​
'description':​
'Page number of the results to fetch. Defaults to 1.'​
},​
'per_page': {​
'type':​
'integer',​
'description':​
'The number of results per page (max 100). Defaults
to 30.'​
}​
},​
'required': ['query']​
}​
})​
def search_repository_code(query: str,​
sort: Optional[str] = 'best match',​
order: Optional[str] = 'desc',​
page: Optional[int] = 1,​
per_page: Optional[int] = 30) -> Dict[str,
Any]

Search for code within repositories.

Searches for query terms inside of files. This method returns up to 100 results per page.

The query can contain any combination of search keywords and qualifiers.
Note: Due to the complexity of searching code, there are a few restrictions:

• Only the default branch is considered. In most cases, this will be the master branch.

• Only files smaller than 384 KB are searchable.

• You must always include at least one search term when searching source code.

For example, searching for language:go is not valid, while amazing language:go is.

Args:
query (str): The search query string. Can contain any combination of search keywords and
qualifiers.

Examples:

• `"addClass in:file language:js repo:jquery/jquery"`: Find files containing

'addClass' in the jquery/jquery repository

• `"repo:octocat/Spoon-Knife css"`: Find instances of 'css' in the

octocat/Spoon-Knife repository

• `"shogun user:heroku language:ruby"`: Find 'shogun' in Ruby files from

heroku's repositories

• `"function size:>10000 language:python"`: Find Python files containing

'function' larger than 10 KB

Supported qualifiers:

• `in:file,path`: Search in file contents and/or file paths. If not specified,

searches in both.

• `language:LANGUAGE`: Filter by programming language (based on file

extension).

Supported languages: javascript (js), python (py), ruby (rb), go, java, c++ (cpp),

typescript (ts), php, c# (cs), html, css, shell (sh), markdown (md).

• `repo:owner/repository`: Restrict search to a specific repository.

• `user:USERNAME`, `org:USERNAME`: Search within a user's or

organization's repositories.

• `size:n`: Filter by file size (in bytes). Can use `>`, `<`, `>=`, `<=`, and `..`
ranges.

• `path:PATH`: Filter by file path.

 • `extension:EXTENSION`: Filter by file extension.

• `is:public`, `is:private`: Filter by repository visibility.

• `fork:true`, `fork:only`: Include forked repositories in the search.

sort (Optional[str]): The field to sort by. Can be 'indexed' or 'best match'.

Defaults to 'best match'.

order (Optional[str]): The direction to sort. Can be 'asc' or 'desc'. Defaults to 'desc'.

page (Optional[int]): Page number of the results to fetch. Defaults to 1.

per_page (Optional[int]): The number of results per page (max 100). Defaults to 30.

Returns:
Dict[str, Any]: A dictionary containing the search results with the following keys:

total_count (int): The total number of matching files found.

incomplete_results (bool): Indicates if the search timed out before finding all results.

items (List[Dict[str, Any]]): A list of code search result items. Each item contains:

name (str): The name of the file.

path (str): The path of the file within the repository.

sha (str): The SHA (blob) of the file.

url (str): The API URL to get the file contents.

git_url (str): The git blob URL.

html_url (str): The URL to view the file in a web browser.

repository (Dict[str, Any]): Details about the repository containing the file:

id (int): The repository ID.

node_id (str): The global node ID of the repository.

name (str): The repository name.

full_name (str): The full name of the repository (owner/repo).

owner (Dict[str, Any]): Details about the repository owner:

login (str): The owner's username.

id (int): The owner's ID.

node_id (str): The owner's global node ID.

type (str): The type of owner (User/Organization).

site_admin (bool): Whether the owner is a site admin.

private (bool): Whether the repository is private.

description (str): The repository description.

fork (bool): Whether the repository is a fork.

score (float): The search relevance score.

Raises:
InvalidInputError: If the search query is missing or invalid, or if pagination parameters are
malformed, not positive integers, or out of acceptable range.

RateLimitError: If the request exceeds the rate limit. Rate limits for search API:

• Authenticated requests: 30 requests per minute

• Unauthenticated requests: 10 requests per minute

search_issues_and_pull_requests
@tool_spec(​
spec={​
'name': 'search_issues_and_pull_requests',​
'description': """ Search for issues and pull requests.​
​
Finds issues and pull requests by searching against a query
string.​
The query can contain any combination of search keywords and
qualifiers.​
​
Supported qualifiers:​
- `is:issue` or `is:pr`: Filters for either issues or pull
requests.​
- `repo:owner/repository`: Restricts the search to a specific
repository.​
- `author:username`: Finds items created by a specific user.​
- `assignee:username`: Finds items assigned to a specific user.​
- `label:"label name"`: Filters by a specific label. Use quotes
for labels with spaces.​
- `state:open` or `state:closed`: Filters by the state.​
- `in:title,body`: Searches for keywords in the title, body, or
both. """,​
'parameters': {​
 'type': 'object',​
'properties': {​
'query': {​
'type':​
'string',​
'description':​
'The search query string, including any qualifiers.'​
},​
'sort': {​
'type':​
'string',​
'description':​
""" The field to sort by. Can be 'created',
'updated', or 'comments'.​
Defaults to `None` (best-match). """​
},​
'order': {​
'type':​
'string',​
'description':​
"The direction to sort. Can be 'asc' or 'desc'.
Defaults to 'desc'."​
},​
'page': {​
'type':​
'integer',​
'description':​
'Page number of the results to fetch. Defaults to 1.'​
},​
'per_page': {​
'type':​
'integer',​
'description':​
'The number of results per page (max 100). Defaults
to 30.'​
}​
},​
'required': ['query']​
}​
})​
def search_issues_and_pull_requests(​
query: str,​
sort: Optional[str] = None,​
order: Optional[str] = "desc",​
page: Optional[int] = 1,​
per_page: Optional[int] = 30) -> Dict[str, Any]

Search for issues and pull requests.

Finds issues and pull requests by searching against a query string.

The query can contain any combination of search keywords and qualifiers.

Supported qualifiers:

• `is:issue` or `is:pr`: Filters for either issues or pull requests.

• `repo:owner/repository`: Restricts the search to a specific repository.

• `author:username`: Finds items created by a specific user.

• `assignee:username`: Finds items assigned to a specific user.

• `label:"label name"`: Filters by a specific label. Use quotes for labels with spaces.

• `state:open` or `state:closed`: Filters by the state.

• `in:title,body`: Searches for keywords in the title, body, or both.

Args:
query (str): The search query string, including any qualifiers.

sort (Optional[str]): The field to sort by. Can be 'created', 'updated', or 'comments'.

Defaults to `None` (best-match).

order (Optional[str]): The direction to sort. Can be 'asc' or 'desc'. Defaults to 'desc'.

page (Optional[int]): Page number of the results to fetch. Defaults to 1.

per_page (Optional[int]): The number of results per page (max 100). Defaults to 30.

Returns:
Dict[str, Any]: A dictionary containing the search results, with the following keys:

• total_count (int): The total number of issues found.

• incomplete_results (bool): Indicates if the search timed out. Always False in

this simulation.

• items (List[Dict[str, Any]]): A list of issue objects matching the search

criteria.

Each issue object contains:

• id (int): Unique identifier for the issue.

• node_id (str): Global identifier for the node.

• number (int): The number of the issue within its repository.

• title (str): The title of the issue.

 • user (Dict[str, Any]): Details of the user who created the issue.

• login (str): The username of the creator.

• id (int): The unique identifier for the creator.

• labels (List[Dict[str, Any]]): A list of labels associated with the

issue.

• name (str): The name of the label.

• color (str): The hexadecimal color code of the label.

• state (str): The current state of the issue (e.g., 'open', 'closed').

• assignee (Optional[Dict[str, Any]]): Details of the user assigned to

the issue.

• login (str): The username of the assignee.

• id (int): The unique identifier for the assignee.

• comments (int): The number of comments on the issue.

• created_at (str): The timestamp (ISO 8601 format) of when the

issue was created.

• updated_at (str): The timestamp (ISO 8601 format) of when the

issue was last updated.

• score (float): The search relevance score for the issue.

Raises:
custom_errors.InvalidInputError: If the search query is missing or invalid,

or if pagination parameters are incorrect.

list_repository_issues
@tool_spec(​
spec={​
'name': 'list_repository_issues',​
'description': """ List and filter repository issues.​
​
Lists and filters issues for a specified repository. This
function allows​
retrieval of issues based on criteria such as their state (e.g.,
open,​
closed, all), associated labels, and a 'since' timestamp
indicating the​
minimum update time. The results can be sorted by fields like
'created',​
'updated', or 'comments', in either ascending ('asc') or
descending​
('desc') order. Pagination is supported through 'page' and
'per_page'​
parameters to manage the volume of returned data. """,​
'parameters': {​
'type': 'object',​
'properties': {​
'owner': {​
'type': 'string',​
'description': 'The owner of the repository.'​
},​
'repo': {​
'type': 'string',​
'description': 'The name of the repository.'​
},​
'state': {​
'type':​
'string',​
'description':​
""" The state of the issues to return (e.g., 'open',​
'closed', 'all'). Defaults to None. """​
},​
'labels': {​
'type': 'array',​
'description':​
'A list of label names to filter issues by. Defaults
to None.',​
'items': {​
'type': 'string'​
}​
},​
'sort': {​
'type':​
'string',​
'description':​
""" The criteria for sorting the issues (e.g.,
'created',​
'updated', 'comments'). Defaults to None. """​
},​
'direction': {​
'type':​
'string',​
'description':​
"The direction of sorting (e.g., 'asc', 'desc').
Defaults to None."​
},​
'since': {​
 'type':​
'string',​
'description':​
""" An ISO 8601 timestamp to filter issues updated at​
or after this time. Defaults to None. """​
},​
'page': {​
'type':​
'integer',​
'description':​
'The page number for paginated results. Defaults to
1.'​
},​
'per_page': {​
'type':​
'integer',​
'description':​
'The number of issues to return per page. Defaults to
30.'​
}​
},​
'required': ['owner', 'repo']​
}​
})​
def list_repository_issues(​
owner: str,​
repo: str,​
state: Optional[str] = None,​
labels: Optional[List[str]] = None,​
sort: Optional[str] = None,​
direction: Optional[str] = None,​
since: Optional[str] = None,​
page: Optional[int] = 1,​
per_page: Optional[int] = 30) -> List[Dict[str, Any]]

List and filter repository issues.

Lists and filters issues for a specified repository. This function allows

retrieval of issues based on criteria such as their state (e.g., open,

closed, all), associated labels, and a 'since' timestamp indicating the

minimum update time. The results can be sorted by fields like 'created',

'updated', or 'comments', in either ascending ('asc') or descending

('desc') order. Pagination is supported through 'page' and 'per_page'

parameters to manage the volume of returned data.

Args:
owner (str): The owner of the repository.

repo (str): The name of the repository.

state (Optional[str]): The state of the issues to return (e.g., 'open',

'closed', 'all'). Defaults to None.

labels (Optional[List[str]]): A list of label names to filter issues by. Defaults to None.

sort (Optional[str]): The criteria for sorting the issues (e.g., 'created',

'updated', 'comments'). Defaults to None.

direction (Optional[str]): The direction of sorting (e.g., 'asc', 'desc'). Defaults to None.

since (Optional[str]): An ISO 8601 timestamp to filter issues updated at

or after this time. Defaults to None.

page (Optional[int]): The page number for paginated results. Defaults to 1.

per_page (Optional[int]): The number of issues to return per page. Defaults to 30.

Returns:
List[Dict[str, Any]]: A list of dictionaries, where each dictionary

represents an issue matching the filter criteria. Each issue

dictionary contains the following keys:

• id (int): The unique ID of the issue.

• node_id (str): The global node ID of the issue.

• number (int): The issue number within the repository.

• title (str): The title of the issue.

• user (Dict[str, Any]): The user who created the issue. This

dictionary contains the following keys:

• login (str): Username.

• id (int): User ID.

• node_id (str): The global node ID of the user.

• type (str): Type of user (e.g., 'User', 'Bot').

 • site_admin (bool): Whether the user is a site administrator.

• labels (List[Dict[str, Any]]): A list of labels associated with the

issue. Each dictionary in this list represents a label and

contains the following keys:

• id (int): Label ID.

• node_id (str): The global node ID of the label.

• name (str): Label name.

• color (str): Label color (hex code).

• description (Optional[str]): Label description.

• default (bool): Indicates if this is a default label.

• state (str): The state of the issue (e.g., 'open', 'closed').

• locked (bool): Whether the issue is locked.

• active_lock_reason (Optional[str]): The reason for locking the

issue, if applicable.

• assignee (Optional[Dict[str, Any]]): The user assigned to this issue

(if any). If present, this dictionary contains the following

keys:

• login (str): Username.

• id (int): User ID.

• node_id (str): The global node ID of the user.

• type (str): Type of user (e.g., 'User', 'Bot').

• site_admin (bool): Whether the user is a site administrator.

• assignees (List[Dict[str, Any]]): A list of users assigned to this

issue. Each user dictionary in this list contains the

following keys:

• login (str): Username.

 • id (int): User ID.

• node_id (str): The global node ID of the user.

• type (str): Type of user (e.g., 'User', 'Bot').

• site_admin (bool): Whether the user is a site administrator.

• milestone (Optional[Dict[str, Any]]): The milestone associated with

the issue (if any). If present, this dictionary contains the

following keys:

• id (int): Milestone ID.

• node_id (str): The global node ID of the milestone.

• number (int): Milestone number within the repository.

• title (str): Milestone title.

• description (Optional[str]): Milestone description.

• creator (Dict[str, Any]): The user who created the milestone.

This dictionary contains the following keys:

• login (str): Username.

• id (int): User ID.

• node_id (str): The global node ID of the user.

• type (str): Type of user (e.g., 'User', 'Bot').

• site_admin (bool): Whether the user is a site administrator.

• open_issues (int): Number of open issues in this milestone.

• closed_issues (int): Number of closed issues in this milestone.

• state (str): State of the milestone (e.g., 'open', 'closed').

• created_at (str): ISO 8601 timestamp of when the milestone

was created.

• updated_at (str): ISO 8601 timestamp of when the milestone

was last updated.

 • closed_at (Optional[str]): ISO 8601 timestamp of when the

milestone was closed.

• due_on (Optional[str]): ISO 8601 timestamp of the milestone

due date.

• comments (int): The number of comments on the issue.

• created_at (str): ISO 8601 timestamp of when the issue was created.

• updated_at (str): ISO 8601 timestamp of when the issue was last

updated.

• closed_at (Optional[str]): ISO 8601 timestamp of when the issue was

closed.

• body (Optional[str]): The content/description of the issue.

• reactions (Dict[str, Any]): Reaction summary. This dictionary

contains the following keys:

• total_count (int): Total number of reactions.

• '+1' (int): Number of '+1' reactions.

• '-1' (int): Number of '-1' reactions.

• laugh (int): Number of 'laugh' reactions.

• hooray (int): Number of 'hooray' reactions.

• confused (int): Number of 'confused' reactions.

• heart (int): Number of 'heart' reactions.

• rocket (int): Number of 'rocket' reactions.

• eyes (int): Number of 'eyes' reactions.

• author_association (str): The relationship of the issue author to

the repository (e.g., 'OWNER', 'MEMBER', 'COLLABORATOR',

'CONTRIBUTOR', 'FIRST_TIMER', 'FIRST_TIME_CONTRIBUTOR',

'MANNEQUIN', 'NONE').
Raises:
NotFoundError: If the repository does not exist.

ValidationError: If filter parameters are invalid.

InvalidDateTimeFormatError: If the 'since' parameter format is invalid.

update_issue
@tool_spec(​
spec={​
'name': 'update_issue',​
'description': """ Update an existing issue in a GitHub
repository.​
​
This function updates an existing issue within a specified GitHub
repository.​
It allows modification of the issue's title, body, state (open or
closed),​
associated labels, assigned users, and milestone. The title and
body can​
be cleared by passing `None`. Labels and assignees are replaced
if new lists​
are provided; an empty list clears them.​
The `updated_at` timestamp is always modified on a successful
call. """,​
'parameters': {​
'type': 'object',​
'properties': {​
'owner': {​
'type':​
'string',​
'description':​
'The account owner of the repository.
Case-insensitive.'​
},​
'repo': {​
'type': 'string',​
'description':​
'The name of the repository. Case-insensitive.'​
},​
'issue_number': {​
'type':​
'integer',​
'description':​
'The number that identifies the issue. Must be
positive.'​
},​
'title': {​
'type':​
 'string',​
'description':​
""" The new title for the issue. If `None` (default
or explicit),​
the title is cleared (set to `None`). """​
},​
'body': {​
'type':​
'string',​
'description':​
""" The new contents of the issue. If `None` (default
or explicit),​
the body is cleared (set to `None`). """​
},​
'state': {​
'type':​
'string',​
'description':​
""" The new state ("open" or "closed"). If `None`
(default),​
the state is not changed. """​
},​
'labels': {​
'type': 'array',​
'description':​
""" List of label names to apply. Replaces existing
labels.​
- If `None` (default): Labels are not changed.​
- If `[]` (empty list): All labels are removed.​
- If list of strings: These become the new labels.
Each name must exist.​
Requires push access. """,​
'items': {​
'type': 'string'​
}​
},​
'assignees': {​
'type': 'array',​
'description':​
""" List of assignee logins. Replaces existing
assignees.​
The first login becomes the primary assignee.​
- If `None` (default): Assignees are not changed.​
- If `[]` (empty list): All assignees are removed.​
- If list of logins: These become the new assignees.
Each login must exist.​
Requires push access. """,​
'items': {​
'type': 'string'​
 }​
},​
'milestone': {​
'type':​
'integer',​
'description':​
""" The number of the milestone to assign.​
- If `None` (default or explicitly passed as `None`):
Removes the current milestone.​
- If a positive integer: Assigns to this milestone.
Must exist in the repository.​
- Note: Milestone number 0 is not valid and will
raise a ValidationError.​
Requires push access for any change to the milestone
(setting or removing). """​
}​
},​
'required': ['owner', 'repo', 'issue_number']​
}​
})​
def update_issue(owner: str,​
repo: str,​
issue_number: int,​
title: Optional[str] = None,​
body: Optional[str] = None,​
state: Optional[str] = None,​
labels: Optional[List[str]] = None,​
assignees: Optional[List[str]] = None,​
milestone: Optional[int] = None) -> Dict[str, Any]

Update an existing issue in a GitHub repository.

This function updates an existing issue within a specified GitHub repository.

It allows modification of the issue's title, body, state (open or closed),

associated labels, assigned users, and milestone. The title and body can

be cleared by passing `None`. Labels and assignees are replaced if new lists

are provided; an empty list clears them.

The `updated_at` timestamp is always modified on a successful call.

Args:
owner (str): The account owner of the repository. Case-insensitive.

repo (str): The name of the repository. Case-insensitive.

issue_number (int): The number that identifies the issue. Must be positive.
title (Optional[str]): The new title for the issue. If `None` (default or explicit),

the title is cleared (set to `None`).

body (Optional[str]): The new contents of the issue. If `None` (default or explicit),

the body is cleared (set to `None`).

state (Optional[str]): The new state ("open" or "closed"). If `None` (default),

the state is not changed.

labels (Optional[List[str]]): List of label names to apply. Replaces existing labels.

• If `None` (default): Labels are not changed.

• If `[]` (empty list): All labels are removed.

• If list of strings: These become the new labels. Each name must exist.

Requires push access.

assignees (Optional[List[str]]): List of assignee logins. Replaces existing assignees.

The first login becomes the primary assignee.

• If `None` (default): Assignees are not changed.

• If `[]` (empty list): All assignees are removed.

• If list of logins: These become the new assignees. Each login must exist.

Requires push access.

milestone (Optional[int]): The number of the milestone to assign.

• If `None` (default or explicitly passed as `None`): Removes the current

milestone.

• If a positive integer: Assigns to this milestone. Must exist in the repository.

• Note: Milestone number 0 is not valid and will raise a ValidationError.

Requires push access for any change to the milestone (setting or removing).

Returns:
Dict[str, Any]: Details of the updated issue. Contains:

• id (int): Unique ID of the issue.

• node_id (str): GraphQL node ID.

• number (int): Issue number within the repository.

• title (Optional[str]): Title of the issue.

• user (Dict[str, Any]): Creator of the issue.

• login (str): Username.

• id (int): User ID.

• node_id (str): User's GraphQL node ID.

• type (str): User type (e.g., "User").

• site_admin (bool): Whether the user is a site administrator.

• labels (List[Dict[str, Any]]): Associated labels. Each label:

• id (int): Label ID.

• node_id (str): Label's GraphQL node ID.

• name (str): Label name.

• color (str): Label color (hex code).

• description (Optional[str]): Label description.

• default (bool): Whether it's a default label.

• state (str): Current state ("open" or "closed").

• locked (bool): Whether the issue is locked.

• assignee (Optional[Dict[str, Any]]): Primary assignee (if any). Same

structure as `user` fields.

• assignees (List[Dict[str, Any]]): All assigned users. Each with same

structure as `user` fields.

• milestone (Optional[Dict[str, Any]]): Associated milestone. If present:

• id (int): Milestone ID.

• node_id (str): Milestone's GraphQL node ID.

• number (int): Milestone number.

• title (str): Milestone title.

• description (Optional[str]): Milestone description.

 • creator (Dict[str, Any]): User who created the milestone. Same
structure as `user` fields.

• open_issues (int): Count of open issues in this milestone.

• closed_issues (int): Count of closed issues in this milestone.

• state (str): Milestone state ("open" or "closed").

• created_at (str): ISO 8601 timestamp of creation.

• updated_at (str): ISO 8601 timestamp of last update.

• due_on (Optional[str]): ISO 8601 timestamp of due date.

• closed_at (Optional[str]): ISO 8601 timestamp of closure.

• comments (int): Number of comments.

• created_at (str): ISO 8601 timestamp of issue creation.

• updated_at (str): ISO 8601 timestamp of issue last update.

• closed_at (Optional[str]): ISO 8601 timestamp of issue closure (if closed).

• body (Optional[str]): Content of the issue.

• author_association (str): Relationship of issue creator to repository (e.g.,

"OWNER", "CONTRIBUTOR").

Raises:
NotFoundError: If repository or issue is not found.

ForbiddenError: If user lacks permission to update.

ValidationError: If input parameters are invalid.

get_issue_comments
@tool_spec(​
spec={​
'name': 'get_issue_comments',​
'description': """ Get comments for a GitHub issue.​
​
This function gets comments for a GitHub issue. The issue is
identified using​
the provided repository owner, repository name, and issue number.
""",​
'parameters': {​
'type': 'object',​
'properties': {​
 'owner': {​
'type': 'string',​
'description': 'The owner of the repository.'​
},​
'repo': {​
'type': 'string',​
'description': 'The name of the repository.'​
},​
'issue_number': {​
'type': 'integer',​
'description': 'The number of the issue.'​
}​
},​
'required': ['owner', 'repo', 'issue_number']​
}​
})​
def get_issue_comments(owner: str, repo: str,​
issue_number: int) -> List[Dict[str, Any]]

Get comments for a GitHub issue.

This function gets comments for a GitHub issue. The issue is identified using

the provided repository owner, repository name, and issue number.

Args:
owner (str): The owner of the repository.

repo (str): The name of the repository.

issue_number (int): The number of the issue.

Returns:
List[Dict[str, Any]]: A list of comment objects for the issue. Each dictionary

in the list represents a comment and has the following structure:

id (int): The unique ID of the comment.

node_id (str): The global node ID of the comment.

user (Dict[str, Any]): Details of the user who created the comment. This

dictionary contains the following keys:

login (str): Username of the comment author.

id (int): User ID of the comment author.

created_at (str): ISO 8601 timestamp indicating when the comment was
created.

updated_at (str): ISO 8601 timestamp indicating when the comment was

last updated.

author_association (str): The relationship of the comment author to the

repository (e.g., 'OWNER', 'MEMBER', 'CONTRIBUTOR', 'NONE').

body (str): The textual content of the comment.

Raises:
NotFoundError: If the repository or issue does not exist.

ValidationError: If input parameters for update are invalid.

get_issue_content
@tool_spec(​
spec={​
'name': 'get_issue_content',​
'description': """ Gets the contents of an issue within a
repository.​
​
This function retrieves detailed information about a specific
issue identified​
by its number, belonging to the specified repository and owner.
The returned​
dictionary is a direct representation of the data for the found
issue. """,​
'parameters': {​
'type': 'object',​
'properties': {​
'owner': {​
'type':​
'string',​
'description':​
""" The username of the account that owns the
repository.​
Must be a non-empty string. """​
},​
'repo': {​
'type':​
'string',​
'description':​
'The name of the repository. Must be a non-empty
string.'​
},​
'issue_number': {​
'type':​
 'integer',​
'description':​
'The number that identifies the issue. Must be a
positive integer.'​
}​
},​
'required': ['owner', 'repo', 'issue_number']​
}​
})​
def get_issue_content(owner: str, repo: str,​
issue_number: int) -> Dict[str, Any]

Gets the contents of an issue within a repository.

This function retrieves detailed information about a specific issue identified

by its number, belonging to the specified repository and owner. The returned

dictionary is a direct representation of the data for the found issue.

Args:
owner (str): The username of the account that owns the repository.

Must be a non-empty string.

repo (str): The name of the repository. Must be a non-empty string.

issue_number (int): The number that identifies the issue. Must be a positive integer.

Returns:
Dict[str, Any]: A dictionary containing the details of the issue.

The expected structure includes:

id (int): The unique ID of the issue.

node_id (str): The global node ID of the issue.

repository_id (int): ID of the repository this issue belongs to.

number (int): Issue number, unique per repository.

title (str): The title of the issue.

user (Dict[str, Any]): The user who created the issue. This dictionary

contains the following fields:

login (str): Username of the user.

id (int): User ID of the user.

node_id (Optional[str]): Global node ID of the user.

type (Optional[str]): Type of account, e.g., 'User' or 'Organization'.

site_admin (Optional[bool]): Whether the user is a site administrator.

labels (List[Dict[str, Any]]): A list of labels associated with the issue.

Each dictionary in the list represents a label and contains the

following fields:

id (int): Label ID.

node_id (str): Global node ID of the label.

repository_id (int): ID of the repository this label belongs to.

name (str): Label name.

color (str): Label color (hex code).

description (Optional[str]): Label description.

default (Optional[bool]): Whether this is a default label.

state (str): State of the issue; either 'open' or 'closed'.

locked (bool): Whether the issue is locked.

assignee (Optional[Dict[str, Any]]): The user assigned to the issue (if any).

If present, this dictionary contains the following fields:

login (str): Username of the assignee.

id (int): User ID of the assignee.

node_id (Optional[str]): Global node ID of the assignee.

type (Optional[str]): Type of account, e.g., 'User' or 'Organization'.

site_admin (Optional[bool]): Whether the assignee is a site administrator.

assignees (List[Dict[str, Any]]): A list of users assigned to the issue.

Each dictionary in the list represents an assignee and contains the

following fields:

login (str): Username of the assignee.

id (int): User ID of the assignee.

node_id (Optional[str]): Global node ID of the assignee.

type (Optional[str]): Type of account, e.g., 'User' or 'Organization'.

site_admin (Optional[bool]): Whether the assignee is a site administrator.

milestone (Optional[Dict[str, Any]]): The milestone associated with the issue (if any).

If present, this dictionary contains the following fields:

id (int): Milestone ID.

node_id (str): Global node ID of the milestone.

repository_id (int): ID of the repository this milestone belongs to.

number (int): The number of the milestone, unique per repository.

title (str): Milestone title.

description (Optional[str]): Milestone description.

creator (Optional[Dict[str, Any]]): The user who created the milestone.

If present, this dictionary contains:

login (str): Username of the creator.

id (int): User ID of the creator.

node_id (Optional[str]): Global node ID of the creator.

type (Optional[str]): Type of account, e.g., 'User' or 'Organization'.

site_admin (Optional[bool]): Whether the creator is a site administrator.

open_issues (int): Number of open issues in this milestone.

closed_issues (int): Number of closed issues in this milestone.

state (str): State of the milestone (e.g., 'open', 'closed').

created_at (str): ISO 8601 timestamp of when the milestone was created.

updated_at (str): ISO 8601 timestamp of when the milestone was last updated.

closed_at (Optional[str]): ISO 8601 timestamp of when the milestone was closed.

due_on (Optional[str]): ISO 8601 timestamp of when the milestone is due.

comments (int): The number of comments on the issue.

created_at (str): ISO 8601 timestamp of when the issue was created.

updated_at (str): ISO 8601 timestamp of when the issue was last updated.

closed_at (Optional[str]): ISO 8601 timestamp of when the issue was closed.

body (Optional[str]): The content of the issue.

author_association (str): The relationship of the issue author to the

repository. Possible values are: "COLLABORATOR", "CONTRIBUTOR",

"FIRST_TIMER", "FIRST_TIME_CONTRIBUTOR", "MANNEQUIN", "MEMBER",

"NONE", "OWNER".

active_lock_reason (Optional[str]): The active lock reason if the issue is locked.

reactions (Optional[Dict[str, Any]]): A dictionary summarizing the reactions to the issue.

If present, this dictionary typically includes fields such as:

url (str): URL to the reactions API endpoint for this issue.

total_count (int): Total number of reactions.

"+1" (int): Count of '+1' (thumbs up) reactions.

"-1" (int): Count of '-1' (thumbs down) reactions.

laugh (int): Count of 'laugh' reactions.

hooray (int): Count of 'hooray' reactions.

confused (int): Count of 'confused' reactions.

heart (int): Count of 'heart' reactions.

rocket (int): Count of 'rocket' reactions.

eyes (int): Count of 'eyes' reactions.

score (Optional[float]): Search score if the issue was retrieved from search results.

Raises:
TypeError: If any of the input arguments are of an incorrect type.

ValueError: If `owner` or `repo` are empty strings, or if `issue_number` is not positive.

NotFoundError: If the repository or issue does not exist.

ValidationError: If the issue data is malformed.

create_issue
@tool_spec(​
spec={​
'name': 'create_issue',​
'description': """ Create a new issue in a GitHub repository.​
​
This function facilitates the creation of a new issue within a
designated GitHub repository.​
It accepts details such as the issue's title, an optional body,
optional assignees,​
and optional labels to initialize the issue. """,​
'parameters': {​
'type': 'object',​
'properties': {​
'owner': {​
'type': 'string',​
'description': 'The owner of the repository.'​
},​
'repo': {​
'type':​
'string',​
'description':​
'The name of the repository. Must be 1-100 characters
and can include alphanumeric characters, hyphens, underscores, or
periods.'​
},​
'title': {​
'type': 'string',​
'description': 'The title for the new issue.'​
},​
'body': {​
'type': 'string',​
'description':​
'The contents of the issue. Default to None.'​
},​
'assignees': {​
'type': 'array',​
'description':​
'A list of GitHub logins to assign to this issue.
Default to None.',​
'items': {​
'type': 'string'​
}​
},​
'labels': {​
 'type': 'array',​
'description':​
'A list of label names to add to this issue. Default
to None.',​
'items': {​
'type': 'string'​
}​
}​
},​
'required': ['owner', 'repo', 'title']​
}​
})​
def create_issue(owner: str,​
repo: str,​
title: str,​
body: Optional[str] = None,​
assignees: Optional[List[str]] = None,​
labels: Optional[List[str]] = None) -> Dict[str, Any]

Create a new issue in a GitHub repository.

This function facilitates the creation of a new issue within a designated GitHub repository.

It accepts details such as the issue's title, an optional body, optional assignees,

and optional labels to initialize the issue.

Args:
owner (str): The owner of the repository.

repo (str): The name of the repository. Must be 1-100 characters and can include
alphanumeric characters, hyphens, underscores, or periods.

title (str): The title for the new issue.

body (Optional[str]): The contents of the issue. Default to None.

assignees (Optional[List[str]]): A list of GitHub logins to assign to this issue. Default to None.

labels (Optional[List[str]]): A list of label names to add to this issue. Default to None.

Returns:
Dict[str, Any]: A dictionary containing details of the created issue with the following keys:

id (int): The unique ID of the issue.

node_id (str): The global node ID of the issue.

number (int): The issue number within the repository.

title (str): The title of the issue.

user (Dict[str, Any]): The user who created the issue. The dictionary contains:

login (str): Username.

id (int): User ID.

node_id (str): The global node ID of the user.

type (str): The type of the account (e.g., 'User').

site_admin (bool): Whether the user is a site administrator.

labels (List[Dict[str, Any]]): A list of labels associated with the issue. Each dictionary in the
list contains:

id (int): Label ID.

node_id (str): The global node ID of the label.

name (str): Label name.

color (str): Label color (hex code).

description (Optional[str]): Label description.

default (bool): Whether this is a default label.

state (str): The state of the issue (e.g., 'open', 'closed').

locked (bool): Whether the issue is locked.

assignee (Optional[Dict[str, Any]]): The user assigned to the issue (if any). If present, the
dictionary contains:

login (str): Username.

id (int): User ID.

node_id (str): The global node ID of the user.

type (str): The type of the account (e.g., 'User').

site_admin (bool): Whether the user is a site administrator.

assignees (List[Dict[str, Any]]): A list of users assigned to the issue. Each dictionary in the
list contains:

login (str): Username.

id (int): User ID.

node_id (str): The global node ID of the user.

type (str): The type of the account (e.g., 'User').

site_admin (bool): Whether the user is a site administrator.

milestone (Optional[Dict[str, Any]]): The milestone associated with the issue. If present, the
dictionary contains:

id (int): Milestone ID.

node_id (str): The global node ID of the milestone.

number (int): Milestone number.

title (str): Milestone title.

description (Optional[str]): Milestone description.

creator (Dict[str, Any]): The user who created the milestone. The dictionary contains:

login (str): Username.

id (int): User ID.

node_id (str): The global node ID of the user.

type (str): The type of the account (e.g., 'User').

site_admin (bool): Whether the user is a site administrator.

open_issues (int): The number of open issues in this milestone.

closed_issues (int): The number of closed issues in this milestone.

state (str): State of the milestone (e.g., 'open', 'closed').

created_at (str): ISO 8601 timestamp of when the milestone was created.

updated_at (str): ISO 8601 timestamp of when the milestone was last updated.

closed_at (Optional[str]): ISO 8601 timestamp of when the milestone was closed.

due_on (Optional[str]): ISO 8601 timestamp of the milestone due date.

comments (int): The number of comments on the issue.

created_at (str): ISO 8601 timestamp of when the issue was created.
updated_at (str): ISO 8601 timestamp of when the issue was last updated.

closed_at (Optional[str]): ISO 8601 timestamp of when the issue was closed (null if open).

body (Optional[str]): The content/body of the issue.

author_association (str): The relationship of the issue author to the repository (e.g.,
'OWNER', 'MEMBER', 'CONTRIBUTOR', 'NONE').

Raises:
NotFoundError: If the repository does not exist.

ValidationError: If required fields (e.g., title) are missing or invalid.

ForbiddenError: If the user does not have permission to create issues in the repository.

NotFoundError: If no authenticated user is found or if the authenticated user cannot be

found in the database.

InternalError: If the issue cannot be created due to an internal data validation error.

add_issue_comment
@tool_spec(​
spec={​
'name': 'add_issue_comment',​
'description': """ Add a comment to an issue.​
​
This function adds a comment to a specific issue. It takes the
repository's​
owner, the repository name, the issue number, and the comment's
body content​
as input. Upon successful execution, it provides a dictionary
containing​
details of the newly created comment. """,​
'parameters': {​
'type': 'object',​
'properties': {​
'owner': {​
'type': 'string',​
'description': 'The owner of the repository.'​
},​
'repo': {​
'type': 'string',​
'description': 'The name of the repository.'​
},​
'issue_number': {​
'type': 'integer',​
'description': 'The number that identifies the
issue.'​
 },​
'body': {​
'type': 'string',​
'description': 'The content of the comment.'​
}​
},​
'required': ['owner', 'repo', 'issue_number', 'body']​
}​
})​
def add_issue_comment(owner: str, repo: str, issue_number: int,​
body: str) -> Dict[str, Any]

Add a comment to an issue.

This function adds a comment to a specific issue. It takes the repository's

owner, the repository name, the issue number, and the comment's body content

as input. Upon successful execution, it provides a dictionary containing

details of the newly created comment.

Args:
owner (str): The owner of the repository.

repo (str): The name of the repository.

issue_number (int): The number that identifies the issue.

body (str): The content of the comment.

Returns:
Dict[str, Any]: A dictionary containing the details of the newly created comment.

It includes the following fields:

id (int): The unique ID of the comment.

node_id (str): The global node ID of the comment.

user (Dict[str, Any]): The user who created the comment. This dictionary

contains:

login (str): Username of the user.

id (int): User ID of the user.

created_at (str): ISO 8601 timestamp of when the comment was created.

updated_at (str): ISO 8601 timestamp of when the comment was last
updated.

author_association (str): The relationship of the comment author to the

repository (e.g., 'OWNER', 'MEMBER', 'CONTRIBUTOR', 'NONE').

body (str): The content of the comment.

Raises:
NotFoundError: If the repository or issue does not exist.

ValidationError: If the comment body is missing or invalid.

ForbiddenError: If the user does not have permission to comment on the issue.