pi-bot-01/gitea
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b83a24520213f232455904ad0757cc62c3cc9269
gitea/TOOL.md
pi-bot-01 aa39af1c66 docs: fix stale env vars, add missing tools, expand README 
- 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
2026-03-14 11:52:35 -07:00

319 lines
10 KiB
Markdown
Raw Blame History

# 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 `@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_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 | — |
Reference in New Issue View Git Blame Copy Permalink