GitHubTool

GitHubTool reference: agents can read repositories, create issues, open pull requests, and call the GitHub API using PyGithub and an access token.

GitHubTool provides methods to interact with GitHub repositories through the GitHub API using PyGithub.

Installation

Install the GitHub dependency:

pip install "agentor[github]"

Constructor

access_token · str · required

GitHub personal access token or OAuth token for authentication

api_key · str

Optional API key for MCP server usage

Methods

get_issue

Get details of a GitHub issue.

repo_name · str · required

Repository name in format owner/repo

issue_number · int · required

Issue number

Returns: String with issue title, body, and state

create_issue

Create a new issue in a repository.

repo_name · str · required

Repository name in format owner/repo

title · str · required

Issue title

body · str

Issue body/description

Returns: URL of the created issue

create_pr

Create a pull request.

repo_name · str · required

Repository name in format owner/repo

title · str · required

Pull request title

head · str · required

Branch name with changes

base · str

Base branch name (default: “main”)

body · str

Pull request description

Returns: URL of the created pull request

Usage

With Agentor agent

import os
from agentor import Agentor
from agentor.tools import GitHubTool

github_tool = GitHubTool(
    access_token=os.getenv("GITHUB_TOKEN")
)

agent = Agentor(
    name="GitHub Assistant",
    model="gpt-4o-mini",
    tools=[github_tool]
)

result = agent.run("Get issue #42 from owner/repo")
print(result)

Creating issues

from agentor.tools import GitHubTool

github = GitHubTool(access_token="ghp_xxx")

# Create an issue
result = github.create_issue(
    repo_name="CelestoAI/agentor",
    title="Feature request: Add XYZ",
    body="Please add support for XYZ feature"
)
print(result)  # Issue created: https://github.com/...

Creating pull requests

# Create a PR from feature branch to main
result = github.create_pr(
    repo_name="CelestoAI/agentor",
    title="Add new feature",
    head="feature-branch",
    base="main",
    body="This PR adds a new feature..."
)
print(result)  # PR created: https://github.com/...

Error handling

The tool returns error messages as strings when operations fail:

# Invalid repository
result = github.get_issue("nonexistent/repo", 1)
print(result)  # GitHub Error: Not Found

# Invalid token
result = github.create_issue("owner/repo", "Test")
print(result)  # GitHub Error: Bad credentials

Source reference

src/agentor/tools/github.py:13