> ## 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 Tools
> Let agents create branches, commit and push code, and open Pull Requests on GitHub
GitHub tools wrap local **git** and the **GitHub CLI (`gh`)** so agents can branch, commit, push, and open pull requests from a repo checkout.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonaiagents.tools import (
github_create_branch,
github_commit_and_push,
github_create_pull_request,
)
agent = Agent(
name="GitHub Release Agent",
instructions="Create a branch, commit staged work, and open a pull request.",
tools=[github_create_branch, github_commit_and_push, github_create_pull_request],
)
agent.start(
"Create branch 'feature/auth', commit with message 'Add JWT auth', "
"then open a PR titled 'Add user authentication feature' targeting main."
)
```
The user describes a git workflow; the agent runs GitHub tools to branch, commit, push, and open a pull request.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "GitHub Tools Flow"
A[Agent] --> B[Create Branch]
B --> C[Commit and Push]
C --> D[Open PR]
D --> E[PR URL]
end
classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
classDef action fill:#189AB4,stroke:#7C90A0,color:#fff
classDef result fill:#10B981,stroke:#7C90A0,color:#fff
class A agent
class B,C,D action
class E result
classDef tool fill:#189AB4,color:#fff
classDef agent fill:#8B0000,color:#fff
```
**Prerequisites:** **git** installed with the working directory inside a repository (`github_create_branch`, `github_commit_and_push`); **`origin` remote** configured for push; **`gh` CLI** installed and authenticated via `gh auth login` (`github_create_pull_request`).
## Quick Start
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonaiagents.tools import (
github_create_branch,
github_commit_and_push,
github_create_pull_request,
)
```
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agent = Agent(
name="GitHub Agent",
tools=[github_create_branch, github_commit_and_push, github_create_pull_request],
)
```
## How It Works
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant Agent
participant Git as git / gh CLI
participant GitHub
User->>Agent: Task
Agent->>Git: github_create_branch
Agent->>Git: github_commit_and_push
Agent->>Git: github_create_pull_request
Git->>GitHub: push + gh pr create
GitHub-->>Agent: PR URL
Agent-->>User: Result
```
## Tools
### `github_create_branch(branch_name: str) -> str`
Creates and checks out a new branch (`git checkout -B`).
| Parameter | Type | Description |
| ------------- | ----- | ------------------------------ |
| `branch_name` | `str` | Branch to create and check out |
Returns a success message or an error string.
### `github_commit_and_push(commit_message: str) -> str`
Stages all changes, commits, and pushes to `origin` on the current branch.
| Parameter | Type | Description |
| ---------------- | ----- | -------------- |
| `commit_message` | `str` | Commit message |
Returns a success message, `"No changes to commit."`, or an error string.
### `github_create_pull_request(title, body, head_branch, base_branch="main") -> str`
Creates a pull request via `gh pr create`.
| Parameter | Type | Default | Description |
| ------------- | ----- | -------- | ---------------------------------------------------- |
| `title` | `str` | — | PR title in the GitHub UI — descriptive and concise |
| `body` | `str` | — | PR description (markdown, issue refs such as `#123`) |
| `head_branch` | `str` | — | Source branch with your changes |
| `base_branch` | `str` | `"main"` | Target branch (`main`, `master`, `develop`, …) |
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
github_create_pull_request(
title="Add user authentication feature",
body="Implements secure login with JWT tokens\n\nFixes #123",
head_branch="feature/auth",
base_branch="main",
)
# -> 'Successfully created Pull Request:\nhttps://github.com/user/repo/pull/456'
```
Returns a success message with the PR URL, or an error if `gh` is missing or unauthenticated.
## Common patterns
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
github_create_branch("feature/docs-update")
github_commit_and_push("docs: update README")
github_create_pull_request(
title="Update README",
body="Clarifies setup steps.",
head_branch="feature/docs-update",
)
```
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
github_create_pull_request(
title="Hotfix for release branch",
body="Patch login timeout.",
head_branch="hotfix/login",
base_branch="release/2.1",
)
```
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# After you have already pushed head_branch
github_create_pull_request(
title="Fix login validation bug",
body="Validates email before sign-in.",
head_branch="fix/login-validation",
)
```
## Best practices
Run `gh auth login` before agents call `github_create_pull_request`. The tool checks `gh auth status` first.
`github_commit_and_push` stages **all** changes (`git add .`). Review the working tree before the agent commits.
Include what changed, why, and linked issues — the `body` field supports markdown.
Tools return error strings rather than raising — check return values in hooks if you need hard failures.
## Related
Example workflow using GitHub tools
Similar CLI-wrapping tools