> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub

> Interact with GitHub repositories, issues, and pull requests

## Overview

GitHub tool allows you to search repositories, manage issues, and interact with GitHub's API.

The user asks about a repo or issue; the agent calls the GitHub API and returns the answer.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "GitHubTool Flow"
        User[👤 User] --> Agent[🤖 Agent]
        Agent --> Tool[🔧 GitHubTool]
        Tool --> Result[✅ Result]
        Result --> Agent
    end

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class User,Agent agent
    class Tool tool
    class Result output
```

## Installation

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install "praisonai[tools]"
```

## Environment Variables

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
export GITHUB_TOKEN=your_personal_access_token
```

Get your token from [GitHub Settings](https://github.com/settings/tokens).

## Quick Start

<Steps>
  <Step title="Simple Usage">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonai_tools import GitHubTool

    # Initialize
    github = GitHubTool()

    # Search repos
    results = github.search_repos("machine learning python")
    print(results)
    ```
  </Step>

  <Step title="With Configuration">
    Use the same tool with an agent — see **Usage with Agent** below, or pass env vars and options from the sections above.
  </Step>
</Steps>

## Usage with Agent

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonai_tools import GitHubTool

agent = Agent(
    name="DevAssistant",
    instructions="You help with GitHub tasks.",
    tools=[GitHubTool()]
)

response = agent.chat("Find popular Python AI frameworks on GitHub")
print(response)
```

## Available Methods

### search\_repos(query, limit=10)

Search GitHub repositories.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai_tools import GitHubTool

github = GitHubTool()
repos = github.search_repos("langchain", limit=5)
```

### get\_repo(owner, repo)

Get repository details.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
repo = github.get_repo("MervinPraison", "PraisonAI")
```

### list\_issues(owner, repo, state="open")

List repository issues.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
issues = github.list_issues("MervinPraison", "PraisonAI", state="open")
```

### create\_issue(owner, repo, title, body)

Create a new issue.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
github.create_issue("owner", "repo", "Bug: Something broken", "Description here")
```

## Common Errors

| Error                         | Cause              | Solution                   |
| ----------------------------- | ------------------ | -------------------------- |
| `GITHUB_TOKEN not configured` | Missing token      | Set environment variable   |
| `Rate limited`                | Too many requests  | Use authenticated requests |
| `Not found`                   | Repo doesn't exist | Check owner/repo name      |

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Tool as Tool
    participant Svc as GitHub API

    User->>Agent: Request
    Agent->>Tool: Call tool
    Tool->>Svc: Query
    Svc-->>Tool: Data
    Tool-->>Agent: Result
    Agent-->>User: Response
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Use a scoped token">
    Read the GitHub token from the environment and grant only the scopes the task needs.
  </Accordion>

  <Accordion title="Handle rate limits">
    GitHub throttles unauthenticated and heavy requests. Authenticate and retry with backoff.
  </Accordion>

  <Accordion title="Paginate large results">
    Fetch issues and commits in pages so the agent processes manageable chunks.
  </Accordion>
</AccordionGroup>

***

## Related Tools

<CardGroup cols={2}>
  <Card title="Bitbucket" icon="book" href="/docs/tools/external/bitbucket">
    Bitbucket repos
  </Card>

  <Card title="Linear" icon="book" href="/docs/tools/external/linear">
    Issue tracking
  </Card>

  <Card title="Jira" icon="book" href="/docs/tools/external/jira">
    Project management
  </Card>
</CardGroup>