# 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 | — |