pi-bot-01/gitea
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: fix stale env vars, add missing tools, expand README

Browse Source 
- 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
This commit is contained in:
pi-bot-01
2026-03-14 11:52:35 -07:00
parent 1412a0fbb9
commit aa39af1c66
3 changed files with 246 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

140
TOOL.md
View File

@@ -1,7 +1,7 @@
# Gitea Tools Reference
All tools use token-based authentication via `GITEA_TOKEN` environment variable.
Owner and repo parameters default to `GITEA_OWNER` and `GITEA_REPO` env vars when omitted.
All tools authenticate via `GITEA_TOKEN`. `owner` and `repo` parameters fall back to
`GITEA_OWNER` / `GITEA_REPO` env vars when omitted.
---
@@ -16,6 +16,8 @@ List repositories accessible to you, or public repos for a specific owner.
| `owner` | string | No | authenticated user | Owner to list repos for |
| `limit` | number | No | 50 | Max results |
---
### `gitea_list_issues`
List issues for a repository.
@@ -27,6 +29,8 @@ List issues for a repository.
| `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.
@@ -39,6 +43,8 @@ Get a single issue by number, including all comments.
**Returns:** Issue title, state, author, labels, body, and all comments.
---
### `gitea_list_prs`
List pull requests for a repository.
@@ -49,6 +55,8 @@ List pull requests for a repository.
| `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.
@@ -61,6 +69,8 @@ Get a single pull request by number, including comments.
**Returns:** PR title, state, author, head/base branches, merge status, body, and all comments.
---
### `gitea_list_runs`
List recent CI/Actions workflow runs.
@@ -71,6 +81,8 @@ List recent CI/Actions workflow runs.
| `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).
@@ -81,6 +93,8 @@ Get full log output for a workflow run (fetches all jobs, downloads each job's l
| `owner` | string | No | `GITEA_OWNER` | Repo owner |
| `repo` | string | No | `GITEA_REPO` | Repo name |
---
### `gitea_get_file_content`
Get file content from a repository.
@@ -108,6 +122,8 @@ Create a new repository for the authenticated user.
| `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.
@@ -118,6 +134,8 @@ Get a repository if it exists, create it if not. Returns clone URL.
| `owner` | string | No | `GITEA_OWNER` | Repo owner |
| `private` | boolean | No | `false` | Private if creating |
---
### `gitea_create_issue`
Create a new issue in a repository.
@@ -129,6 +147,8 @@ Create a new issue in a repository.
| `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.
@@ -140,6 +160,25 @@ Post a comment on an issue or pull request.
| `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.
@@ -149,21 +188,27 @@ Create a new branch from an existing ref.
| `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 |
| `ref` | string | No | `"main"` | Source branch or SHA |
---
### `gitea_update_file`
Create or update a file in a repository. For updates, you must provide the current file's SHA (get it from `gitea_get_file_content`).
Create or update a file in a repository.
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `path` | string | **Yes** | — | File path |
| `content` | string | **Yes** | — | File content |
| `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 (required for updates) |
| `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`
@@ -176,7 +221,9 @@ Create a pull request.
| `base` | string | **Yes** | — | Target branch |
| `owner` | string | No | `GITEA_OWNER` | Repo owner |
| `repo` | string | No | `GITEA_REPO` | Repo name |
| `body` | string | No | `""` | PR description |
| `body` | string | No | `""` | PR description (Markdown) |
---
### `gitea_merge_pr`
@@ -189,34 +236,83 @@ Merge a pull request.
| `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. Uses bearer token auth (not HMAC secrets).
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 auth |
| `events` | string[] | No | `["issues", "issue_comment", "pull_request", "push"]` | Events to listen for |
| `token` | string | No | — | Bearer token for webhook validation |
| `events` | string[] | No | `["issues","issue_comment","pull_request","push"]` | Events to subscribe to |
---
## Authentication
## Management Tools
All API calls use `Authorization: token <GITEA_TOKEN>` header.
### `gitea_repo_config`
Webhook endpoint uses `Authorization: Bearer <PI_WEBHOOK_TOKEN>` for incoming request validation (optional — if not set, endpoint is open).
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 `@botname` appears 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_URL` | Gitea instance URL (default: `https://git.dominat.us`) |
| `GITEA_TOKEN` | Gitea API token (**required**) |
| `GITEA_OWNER` | Default repo owner |
| `GITEA_REPO` | Default repo name |
| `PI_WEBHOOK_TOKEN` | Bearer token to validate inbound webhooks (optional) |
| `PI_WEBHOOK_HOST` | Webhook server bind host (default: `0.0.0.0`) |
| `PI_WEBHOOK_PORT` | Webhook server port (default: `3000`) |
| `PI_WEBHOOK_URL` | Public URL for webhook registration (used by auto-polling) |
| `PI_BOT_POLL_INTERVAL` | Polling interval in seconds for new repos (default: `300`) |
| `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 | — |