gitea/TOOL.md

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)