GitHub Tools - PraisonAI

GitHub tools wrap local git and the GitHub CLI (gh) so agents can branch, commit, push, and open pull requests from a repo checkout.

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.

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). user.email should match the identity you expect to author commits — the foreign-author guard reads git config user.email.

Quick Start

Simple Usage

from praisonaiagents import Agent
from praisonaiagents.tools import (
    github_create_branch,
    github_commit_and_push,
    github_create_pull_request,
)

With Configuration

agent = Agent(
    name="GitHub Agent",
    tools=[github_create_branch, github_commit_and_push, github_create_pull_request],
)

How It Works

You don’t have to think about branch safety — the tool quietly does the right thing.

User: “Commit and push what I have.” Agent: (tool auto-creates praisonai/fix-login-a1b2c3, pushes there, and reports the branch name back)

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, branch=None, allow_unsafe_branch=False) -> str`

Stages all changes, commits, and pushes to origin — with branch-safety guardrails that refuse unsafe pushes and never force-push.

Parameter	Type	Default	Description
`commit_message`	`str`	—	Commit message
`branch`	`Optional[str]`	`None`	Target branch. Defaults to the current branch.
`allow_unsafe_branch`	`bool`	`False`	Opt-in override for default-branch and foreign-author refusals. Divergence is never overridable.

Returns a success message, "No changes to commit.", or an error string.

Branch-safety rules

The tool checks these rules before committing, so a refusal leaves your changes intact.

Agent branches are always allowed. Any branch whose name starts with praisonai/ skips the default and foreign-author checks.
The default branch is never pushed directly. On main (or when branch="main"), the tool creates a fresh praisonai/{slug}-{6hex} branch from HEAD and pushes there instead.
Foreign commits are refused. If the target branch carries commits authored by someone other than your git config user.email, the push stops.
Divergence is refused, never forced. If the remote branch is not an ancestor of HEAD, the push stops — this is never overridable.
Override with care. allow_unsafe_branch=True (or env PRAISONAI_GIT_ALLOW_UNSAFE_BRANCH=true) bypasses rules 2 and 3, but never rule 4.

from praisonaiagents.tools import github_commit_and_push

# On main: direct push refused, tool creates and pushes an agent branch.
github_commit_and_push("docs: clarify setup steps")
# -> "Successfully committed and pushed changes to new agent branch
#     'praisonai/docs-clarify-setup-steps-a1b2c3' (refused direct push
#     to default branch 'main')"

`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`, …)

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

Auto-branch (safest)
Full PR flow
Non-main base
PR only

from praisonaiagents.tools import github_commit_and_push

# Agent is on main; direct push refused, tool creates praisonai/<slug>-<hex>.
github_commit_and_push("docs: clarify setup steps")
# -> "Successfully committed and pushed changes to new agent branch
#     'praisonai/docs-clarify-setup-steps-a1b2c3' (refused direct push
#     to default branch 'main')"

# Explicit target — same auto-branch behaviour if it is the default.
github_commit_and_push("fix parser", branch="main")

# Opt in to push a non-default, non-agent branch you own.
github_commit_and_push(
    "release notes",
    branch="release/v2",
    allow_unsafe_branch=True,
)

github_create_branch("praisonai/docs-update")
github_commit_and_push("docs: update README")
github_create_pull_request(
    title="Update README",
    body="Clarifies setup steps.",
    head_branch="praisonai/docs-update",
)

Any branch name starting with praisonai/ skips the default and foreign-author refusals.

github_create_pull_request(
    title="Hotfix for release branch",
    body="Patch login timeout.",
    head_branch="hotfix/login",
    base_branch="release/2.1",
)

# 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

Authenticate gh once

Run gh auth login before agents call github_create_pull_request. The tool checks gh auth status first.

Keep commits scoped

github_commit_and_push stages all changes (git add .), so review the working tree for a tidy commit. An over-broad git add . no longer risks an over-broad push to main — the tool refuses unsafe pushes before committing.

Prefer the auto-branch flow

Leaving branch=None while on the default branch is the safest, one-line way to ship a change. The tool picks a praisonai/… name, pushes there, and reports the name in its return string.

When to set allow_unsafe_branch

Only for a branch you own (e.g. release/v2) that carries commits by someone other than the current committer — never for the default branch as a habit. Set env PRAISONAI_GIT_ALLOW_UNSAFE_BRANCH=true for CI. Divergence (force-push) is never allowed regardless.

Write descriptive PR bodies

Include what changed, why, and linked issues — the body field supports markdown.

Handle missing CLI gracefully

Tools return error strings rather than raising — check return values in hooks if you need hard failures.

Linear Bot

Example workflow using GitHub tools

Shell Tools

Similar CLI-wrapping tools

​Quick Start

​How It Works

​Tools

​github_create_branch(branch_name: str) -> str

​github_commit_and_push(commit_message, branch=None, allow_unsafe_branch=False) -> str

​Branch-safety rules

​github_create_pull_request(title, body, head_branch, base_branch="main") -> str

​Common patterns

​Best practices

​Related

Linear Bot

Shell Tools

Quick Start

How It Works

Tools

`github_create_branch(branch_name: str) -> str`

`github_commit_and_push(commit_message, branch=None, allow_unsafe_branch=False) -> str`

Branch-safety rules

`github_create_pull_request(title, body, head_branch, base_branch="main") -> str`

Common patterns

Best practices

Related