pi-bot-01/gitea
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1412a0fbb922200f04f240788093dc54fb3df459
gitea/TOOL.md
pi-bot-01 25e49db155 feat: consolidated Gitea API client and pi extension 
- Pure fetch-based API client (src/) with zero external dependencies
- Pi extension adapter (pi-extension/) registering 17 tools
- Standalone CLI (cli.ts) replacing gitea-scripts/gitea.js
- Token auth everywhere (no HMAC secrets)
- SKILL.md for agent auto-discovery
- TOOL.md with full parameter reference

Consolidates pi-bot/extensions/pi-gitea and clawbot/gitea-scripts
into a single shared package.
2026-03-13 14:49:55 -07:00

223 lines
8.2 KiB
Markdown
Raw Blame History

# 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.
---
## 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_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 |
### `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`).
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `path` | string | **Yes** | — | File path |
| `content` | string | **Yes** | — | File content |
| `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) |
### `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 |
### `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. Uses bearer token auth (not HMAC secrets).
| 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 |
---
## Authentication
All API calls use `Authorization: token <GITEA_TOKEN>` header.
Webhook endpoint uses `Authorization: Bearer <PI_WEBHOOK_TOKEN>` for incoming request validation (optional — if not set, endpoint is open).
| 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`) |
Reference in New Issue View Git Blame Copy Permalink