# 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`) |