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
This commit is contained in:
120
README.md
120
README.md
@@ -2,23 +2,45 @@
|
||||
|
||||
Consolidated Gitea API client and pi extension for git.dominat.us.
|
||||
|
||||
Provides a pure TypeScript Gitea API client (no external dependencies), a pi extension that registers tools for LLM use, and a standalone CLI.
|
||||
Provides a pure TypeScript Gitea API client (zero external dependencies), a pi extension with 22 tools for LLM use, and a standalone CLI. Works as a pi extension in both **pi-bot** (persistent session, webhook server + notification polling) and **openclaw** (ephemeral sessions, tools-only).
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
src/ Core API client (pure fetch, token auth, zero deps)
|
||||
pi-extension/ Pi extension adapter (registers tools + webhook server)
|
||||
cli.ts Standalone CLI
|
||||
SKILL.md Agent skill definition (auto-discovered by pi)
|
||||
TOOL.md Tool reference documentation
|
||||
src/ Core API client (pure fetch, token auth, zero deps)
|
||||
client.ts GiteaClient class + request helpers
|
||||
repos.ts Repo operations
|
||||
issues.ts Issues + comments
|
||||
pulls.ts Pull requests
|
||||
actions.ts CI/Actions workflow runs
|
||||
files.ts File read/write (POST for create, PUT for update)
|
||||
webhooks.ts Webhook management
|
||||
index.ts Re-exports
|
||||
|
||||
pi-extension/ Pi extension adapter
|
||||
index.ts Registers tools, lifecycle hooks, runtime detection
|
||||
tools/
|
||||
read-tools.ts 8 read tools
|
||||
write-tools.ts 12 write + management tools
|
||||
webhook/
|
||||
server.ts Inbound webhook server, notification poller, @mention routing
|
||||
|
||||
cli.ts Standalone CLI (replaces gitea-scripts/gitea.js)
|
||||
SKILL.md Agent skill definition (auto-discovered by pi)
|
||||
TOOL.md Full tool + environment variable reference
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
### As a pi extension
|
||||
|
||||
Add to your `settings.json`:
|
||||
Symlink or copy `pi-extension/` into your `<agentDir>/extensions/` directory:
|
||||
|
||||
```bash
|
||||
ln -sf /path/to/gitea/pi-extension ~/.pi/agent/extensions/pi-gitea
|
||||
```
|
||||
|
||||
Or add to `settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -26,7 +48,19 @@ Add to your `settings.json`:
|
||||
}
|
||||
```
|
||||
|
||||
Or place/symlink `pi-extension/` into your `<agentDir>/extensions/` directory.
|
||||
### In pi-bot (Docker)
|
||||
|
||||
The `pi-bot` Dockerfile mounts the whole package and symlinks it:
|
||||
|
||||
```
|
||||
-v /srv/pods/pi-bot/gitea:/app/gitea:Z
|
||||
```
|
||||
|
||||
`entrypoint.sh` creates `~/.pi/agent/extensions/pi-gitea → /app/gitea/pi-extension` on startup.
|
||||
|
||||
### In openclaw (Docker)
|
||||
|
||||
The `openclaw-custom` Dockerfile copies `gitea/` into `/app/gitea/`. An entrypoint wrapper creates the symlink into `agentDir/extensions/pi-gitea` at container start. Webhook server + polling are disabled automatically (tools only); openclaw's hooks system handles inbound events.
|
||||
|
||||
### As a library
|
||||
|
||||
@@ -35,7 +69,7 @@ import { GiteaClient, listRepos, getIssue } from "./src/index.js";
|
||||
|
||||
const client = new GiteaClient({
|
||||
url: "https://git.dominat.us",
|
||||
token: "your-token",
|
||||
token: process.env.GITEA_TOKEN!,
|
||||
});
|
||||
|
||||
const repos = await listRepos(client);
|
||||
@@ -49,22 +83,76 @@ export GITEA_TOKEN="your-token"
|
||||
npx tsx cli.ts whoami
|
||||
npx tsx cli.ts repos
|
||||
npx tsx cli.ts issues owner/repo
|
||||
npx tsx cli.ts issue owner/repo 42
|
||||
npx tsx cli.ts create-issue owner/repo "Bug title" --body "Description"
|
||||
npx tsx cli.ts comment owner/repo 42 "Fixed in #7"
|
||||
npx tsx cli.ts close owner/repo 42
|
||||
npx tsx cli.ts prs owner/repo
|
||||
npx tsx cli.ts runs owner/repo
|
||||
npx tsx cli.ts logs owner/repo 1234
|
||||
```
|
||||
|
||||
## Runtime Detection
|
||||
|
||||
On `session_start` the extension auto-detects which runtime it's in:
|
||||
|
||||
| Condition | Mode | Behaviour |
|
||||
|-----------|------|-----------|
|
||||
| `ctx.sendUserMessage` exists | **pi-bot** | Events injected directly into session; webhook server + notification poller start |
|
||||
| `GITEA_HOOKS_URL` set | **openclaw** | Events POSTed to `GITEA_HOOKS_URL/hooks/agent`; no server/poller |
|
||||
| `GITEA_ENABLE_POLLING=1` | forced polling | Webhook server + poller start regardless of other settings |
|
||||
|
||||
## @mention Routing
|
||||
|
||||
In collab repos (where the bot isn't the owner), the default response mode is `"mention"` — the bot only responds when its username appears as `@botname` in the text. Own repos default to `"all"`.
|
||||
|
||||
Override per repo with the `gitea_repo_config` tool:
|
||||
|
||||
```
|
||||
gitea_repo_config repo="oc/myrepo" respondTo="all"
|
||||
```
|
||||
|
||||
## Authentication
|
||||
|
||||
All API calls use `Authorization: token <GITEA_TOKEN>` — no HMAC secrets.
|
||||
|
||||
The inbound webhook endpoint optionally validates `Authorization: Bearer <GITEA_WEBHOOK_TOKEN>`.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Required
|
||||
|
||||
| Variable | Purpose |
|
||||
|----------|---------|
|
||||
| `GITEA_TOKEN` | Gitea API token |
|
||||
|
||||
### Core
|
||||
|
||||
| Variable | Purpose | Default |
|
||||
|----------|---------|---------|
|
||||
| `GITEA_URL` | Gitea instance URL | `https://git.dominat.us` |
|
||||
| `GITEA_TOKEN` | API token (required) | — |
|
||||
| `GITEA_OWNER` | Default repo owner | — |
|
||||
| `GITEA_REPO` | Default repo name | — |
|
||||
| `GITEA_USER` | Bot's own username (for @mention detection) | — |
|
||||
| `GITEA_OWNER` | Default repo owner for tools | — |
|
||||
| `GITEA_REPO` | Default repo name for tools | — |
|
||||
|
||||
See [TOOL.md](TOOL.md) for full tool documentation and [SKILL.md](SKILL.md) for the agent skill definition.
|
||||
### pi-bot (webhook server + polling)
|
||||
|
||||
## Auth
|
||||
| Variable | Purpose | Default |
|
||||
|----------|---------|---------|
|
||||
| `GITEA_WEBHOOK_HOST` | Bind address | `0.0.0.0` |
|
||||
| `GITEA_WEBHOOK_PORT` | Inbound webhook port | `3000` |
|
||||
| `GITEA_WEBHOOK_TOKEN` | Bearer token for webhook validation | — (open) |
|
||||
| `GITEA_WEBHOOK_URL` | Public URL registered with Gitea | — |
|
||||
| `GITEA_POLL_INTERVAL` | Repo discovery interval (seconds) | `300` |
|
||||
| `GITEA_NOTIF_INTERVAL` | Notification poll interval (seconds) | `30` |
|
||||
|
||||
All API calls use `Authorization: token <GITEA_TOKEN>` header. No HMAC secrets.
|
||||
### openclaw (hooks delivery)
|
||||
|
||||
Webhook endpoint optionally validates with `Authorization: Bearer <PI_WEBHOOK_TOKEN>`.
|
||||
| Variable | Purpose | Default |
|
||||
|----------|---------|---------|
|
||||
| `GITEA_HOOKS_URL` | openclaw gateway base URL | — |
|
||||
| `GITEA_HOOKS_TOKEN` | Bearer token for the hooks endpoint | — |
|
||||
| `GITEA_HOOKS_PATH` | Hooks endpoint path | `/hooks/agent` |
|
||||
| `GITEA_ENABLE_POLLING` | Set `"1"` to force webhook server + polling | — |
|
||||
|
||||
See [TOOL.md](TOOL.md) for the full tool reference and [SKILL.md](SKILL.md) for the agent skill definition.
|
||||
|
||||
Reference in New Issue
Block a user