Files

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

10 KiB

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	—

10 KiB Raw Blame History

Gitea Tools Reference

Read Tools

gitea_list_repos

gitea_list_issues

gitea_get_issue

gitea_list_prs

gitea_get_pr

gitea_list_runs

gitea_get_run_logs

gitea_get_file_content