pi-bot-01
aa39af1c66
- TOOL.md: rename PI_WEBHOOK_*/PI_BOT_POLL_* → GITEA_* throughout - TOOL.md: add gitea_edit_issue, gitea_repo_config, gitea_tracked_repos - TOOL.md: split env vars into required/tools/webhook/openclaw sections - SKILL.md: add gitea_edit_issue and management tools to quick reference - SKILL.md: add close-issue step to triage workflow - SKILL.md: add Configure Bot Behavior section - README.md: add Runtime Detection table (pi-bot vs openclaw auto-detect) - README.md: add @mention routing section - README.md: add openclaw Docker install instructions - README.md: fix auth note (GITEA_WEBHOOK_TOKEN not PI_WEBHOOK_TOKEN) - README.md: split env table into required/core/webhook/openclaw sections
10 KiB
Gitea Tools Reference
All tools authenticate via GITEA_TOKEN. owner and repo parameters fall back to
GITEA_OWNER / GITEA_REPO env vars when omitted.
Read Tools
gitea_list_repos
List repositories accessible to you, or public repos for a specific owner.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
owner |
string | No | authenticated user | Owner to list repos for |
limit |
number | No | 50 | Max results |
gitea_list_issues
List issues for a repository.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
owner |
string | No | GITEA_OWNER |
Repo owner |
repo |
string | No | GITEA_REPO |
Repo name |
state |
"open" | "closed" | "all" |
No | "open" |
Issue state filter |
limit |
number | No | 20 | Max results |
gitea_get_issue
Get a single issue by number, including all comments.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
index |
number | Yes | — | Issue number |
owner |
string | No | GITEA_OWNER |
Repo owner |
repo |
string | No | GITEA_REPO |
Repo name |
Returns: Issue title, state, author, labels, body, and all comments.
gitea_list_prs
List pull requests for a repository.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
owner |
string | No | GITEA_OWNER |
Repo owner |
repo |
string | No | GITEA_REPO |
Repo name |
state |
"open" | "closed" | "all" |
No | "open" |
PR state filter |
gitea_get_pr
Get a single pull request by number, including comments.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
index |
number | Yes | — | PR number |
owner |
string | No | GITEA_OWNER |
Repo owner |
repo |
string | No | GITEA_REPO |
Repo name |
Returns: PR title, state, author, head/base branches, merge status, body, and all comments.
gitea_list_runs
List recent CI/Actions workflow runs.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
owner |
string | No | GITEA_OWNER |
Repo owner |
repo |
string | No | GITEA_REPO |
Repo name |
limit |
number | No | 10 | Max results |
gitea_get_run_logs
Get full log output for a workflow run (fetches all jobs, downloads each job's logs).
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
run_id |
number | Yes | — | Workflow run ID (numeric id, not run_number) |
owner |
string | No | GITEA_OWNER |
Repo owner |
repo |
string | No | GITEA_REPO |
Repo name |
gitea_get_file_content
Get file content from a repository.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
path |
string | Yes | — | File path (e.g., src/index.ts) |
owner |
string | No | GITEA_OWNER |
Repo owner |
repo |
string | No | GITEA_REPO |
Repo name |
ref |
string | No | default branch | Commit SHA or branch name |
Returns: Decoded file content, SHA (needed for updates), and ref.
Write Tools
gitea_create_repo
Create a new repository for the authenticated user.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name |
string | Yes | — | Repository name |
private |
boolean | No | false |
Private repository |
description |
string | No | "" |
Repository description |
gitea_ensure_repo
Get a repository if it exists, create it if not. Returns clone URL.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name |
string | Yes | — | Repository name |
owner |
string | No | GITEA_OWNER |
Repo owner |
private |
boolean | No | false |
Private if creating |
gitea_create_issue
Create a new issue in a repository.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
title |
string | Yes | — | Issue title |
owner |
string | No | GITEA_OWNER |
Repo owner |
repo |
string | No | GITEA_REPO |
Repo name |
body |
string | No | "" |
Issue body (Markdown) |
gitea_create_issue_comment
Post a comment on an issue or pull request.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
index |
number | Yes | — | Issue/PR number |
body |
string | Yes | — | Comment body (Markdown) |
owner |
string | No | GITEA_OWNER |
Repo owner |
repo |
string | No | GITEA_REPO |
Repo name |
gitea_edit_issue
Edit an issue — change its title, body, or state. Use to close issues when work is done.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
index |
number | Yes | — | Issue number |
owner |
string | No | GITEA_OWNER |
Repo owner |
repo |
string | No | GITEA_REPO |
Repo name |
title |
string | No | unchanged | New title |
body |
string | No | unchanged | New body (Markdown) |
state |
"open" | "closed" |
No | unchanged | New state |
Note: All edit fields are optional — only supplied fields are changed.
gitea_create_branch
Create a new branch from an existing ref.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
branch |
string | Yes | — | Name for the new branch |
owner |
string | No | GITEA_OWNER |
Repo owner |
repo |
string | No | GITEA_REPO |
Repo name |
ref |
string | No | "main" |
Source branch or SHA |
gitea_update_file
Create or update a file in a repository.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
path |
string | Yes | — | File path |
content |
string | Yes | — | File content (plain text, not base64) |
message |
string | Yes | — | Commit message |
owner |
string | No | GITEA_OWNER |
Repo owner |
repo |
string | No | GITEA_REPO |
Repo name |
branch |
string | No | "main" |
Target branch |
sha |
string | No | — | Current file SHA — omit for new files, required for updates |
Tip: Get the SHA for an existing file with gitea_get_file_content first.
gitea_create_pr
Create a pull request.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
title |
string | Yes | — | PR title |
head |
string | Yes | — | Source branch |
base |
string | Yes | — | Target branch |
owner |
string | No | GITEA_OWNER |
Repo owner |
repo |
string | No | GITEA_REPO |
Repo name |
body |
string | No | "" |
PR description (Markdown) |
gitea_merge_pr
Merge a pull request.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
index |
number | Yes | — | PR number |
owner |
string | No | GITEA_OWNER |
Repo owner |
repo |
string | No | GITEA_REPO |
Repo name |
merge_method |
"merge" | "rebase" | "squash" |
No | "merge" |
Merge strategy |
gitea_create_webhook
Create a webhook on a repository (bearer token auth, not HMAC).
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
url |
string | Yes | — | Webhook delivery URL |
owner |
string | No | GITEA_OWNER |
Repo owner |
repo |
string | No | GITEA_REPO |
Repo name |
token |
string | No | — | Bearer token for webhook validation |
events |
string[] | No | ["issues","issue_comment","pull_request","push"] |
Events to subscribe to |
Management Tools
gitea_repo_config
Set how the bot responds to events on a repo.
| Parameter | Type | Required | Description |
|---|---|---|---|
repo |
string | Yes | Repository (owner/name) |
respondTo |
"all" | "mention" |
Yes | Response mode |
"all"— respond to every issue/PR/comment event"mention"— respond only when@botnameappears in the text, or when assigned
Defaults: Repos where the bot is owner default to "all"; collab repos default to "mention".
gitea_tracked_repos
List all repos the bot is currently tracking, with their type and response mode.
No parameters.
Returns: Each tracked repo's name, type (webhook or collab), and respondTo setting.
Environment Variables
Required
| Variable | Purpose |
|---|---|
GITEA_TOKEN |
API token for all Gitea API calls |
Defaults (tools)
| Variable | Purpose | Default |
|---|---|---|
GITEA_URL |
Gitea instance URL | https://git.dominat.us |
GITEA_OWNER |
Default repo owner | — |
GITEA_REPO |
Default repo name | — |
GITEA_USER |
Bot's own username (for @mention detection) | — |
Webhook server (pi-bot mode)
| Variable | Purpose | Default |
|---|---|---|
GITEA_WEBHOOK_HOST |
Bind address for inbound webhook server | 0.0.0.0 |
GITEA_WEBHOOK_PORT |
Port for inbound webhook server | 3000 |
GITEA_WEBHOOK_TOKEN |
Bearer token to validate inbound webhook requests | — (open) |
GITEA_WEBHOOK_URL |
Public URL registered with Gitea repos | — |
GITEA_POLL_INTERVAL |
Repo discovery interval in seconds | 300 |
GITEA_NOTIF_INTERVAL |
Notification polling interval in seconds | 30 |
openclaw / hooks mode
| Variable | Purpose | Default |
|---|---|---|
GITEA_HOOKS_URL |
openclaw gateway URL to POST events to | — |
GITEA_HOOKS_TOKEN |
Bearer token for the openclaw hooks endpoint | — |
GITEA_HOOKS_PATH |
Path on the hooks endpoint | /hooks/agent |
GITEA_ENABLE_POLLING |
Set to "1" to force webhook server + polling even when GITEA_HOOKS_URL is set |
— |