tools.gitea_tools module

Gitea API tools using per-user access tokens.

Provides repository, issue, PR, commit, file, notification, and star operations via the Gitea REST API. Supports custom base URLs for self-hosted instances. Requires set_user_api_key service=gitea.

async tools.gitea_tools.gitea_list_repos(page=1, limit=20, ctx=None)[source]

List the authenticated user’s own Gitea repositories.

Backs the gitea_list_repos tool. Resolves the caller’s token via _get_credentials and pages the GET /user/repos endpoint through _gitea_request, condensing each repository through _fmt_repo so the LLM receives a compact, token-efficient listing rather than the full Gitea payloads. The limit is clamped to 50 to match the instance ceiling. Performs HTTP and a Redis-backed credential read only; no writes.

Registered as the gitea_list_repos handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • page (int) – 1-based page number to fetch.

  • limit (int) – Results per page; values above 50 are clamped to 50.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with a count and a repos array of compact repository summaries, or a JSON error object on API failure.

async tools.gitea_tools.gitea_search_repos(q, sort='updated', order='desc', page=1, limit=20, ctx=None)[source]

Search public and accessible Gitea repositories by keyword.

Backs the gitea_search_repos tool. Resolves credentials via _get_credentials and queries GET /repos/search through _gitea_request with the supplied keyword, sort field, direction, and paging, then condenses each hit through _fmt_repo. Unlike the raw endpoint this unwraps the Gitea data envelope before formatting. Performs HTTP and a Redis-backed credential read only; no writes.

Registered as the gitea_search_repos handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • q (str) – Free-text search keyword.

  • sort (str) – Sort field (e.g. updated, created, stars).

  • order (str) – Sort direction, asc or desc.

  • page (int) – 1-based page number to fetch.

  • limit (int) – Results per page; values above 50 are clamped to 50.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with a count and a repos array of compact repository summaries, or a JSON error object on API failure.

async tools.gitea_tools.gitea_get_repo(owner, repo, ctx=None)[source]

Fetch the details of a single Gitea repository.

Backs the gitea_get_repo tool. Resolves credentials via _get_credentials and requests GET /repos/{owner}/{repo} through _gitea_request, returning the repository condensed through _fmt_repo. Performs HTTP and a Redis-backed credential read only.

Registered as the gitea_get_repo handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with the compact repository summary, or a JSON error object on API failure.

async tools.gitea_tools.gitea_create_repo(name, description='', private=False, auto_init=True, ctx=None)[source]

Create a new repository owned by the authenticated user.

Backs the gitea_create_repo tool. Resolves credentials via _get_credentials and POSTs to /user/repos through _gitea_request with the name, optional description, privacy flag, and an auto_init flag that seeds a README so the repo has a default branch. This mutates server state on the Gitea instance; locally it performs HTTP and a Redis-backed credential read only. The created repo is returned condensed through _fmt_repo.

Registered as the gitea_create_repo handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • name (str) – Name for the new repository.

  • description (str) – Optional repository description; omitted when empty.

  • private (bool) – Whether the repository should be private.

  • auto_init (bool) – Whether to initialise the repository with a README.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with the compact summary of the created repository, or a JSON error object on API failure.

async tools.gitea_tools.gitea_list_issues(owner, repo, state='open', labels='', page=1, limit=20, ctx=None)[source]

List issues on a Gitea repository, optionally filtered by state and labels.

Backs the gitea_list_issues tool. Resolves credentials via _get_credentials and pages GET /repos/{owner}/{repo}/issues through _gitea_request, passing the state filter (open/closed/all) and an optional comma-separated labels filter, then condenses each issue through _fmt_issue. Performs HTTP and a Redis-backed credential read only; no writes.

Registered as the gitea_list_issues handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • state (str) – Issue state filter: open, closed, or all.

  • labels (str) – Optional comma-separated label names to filter by.

  • page (int) – 1-based page number to fetch.

  • limit (int) – Results per page; values above 50 are clamped to 50.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with a count and an issues array of compact issue summaries, or a JSON error object on API failure.

async tools.gitea_tools.gitea_get_issue(owner, repo, index, ctx=None)[source]

Fetch a single issue by its per-repository index number.

Backs the gitea_get_issue tool. Resolves credentials via _get_credentials and requests GET /repos/{owner}/{repo}/issues/{index} through _gitea_request, returning the issue condensed through _fmt_issue. Performs HTTP and a Redis-backed credential read only.

Registered as the gitea_get_issue handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • index (int) – The issue’s per-repository number.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with the compact issue summary, or a JSON error object on API failure.

async tools.gitea_tools.gitea_create_issue(owner, repo, title, body='', labels=None, assignees=None, ctx=None)[source]

Create a new issue on a Gitea repository.

Backs the gitea_create_issue tool. Resolves credentials via _get_credentials and POSTs to /repos/{owner}/{repo}/issues through _gitea_request with the title and any supplied body, label IDs, and assignee usernames, returning the created issue condensed through _fmt_issue. This mutates state on the Gitea instance; locally it performs HTTP and a Redis-backed credential read only.

Registered as the gitea_create_issue handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop. It is also imported and awaited directly by tools.gitea_integration to file issues from higher-level automation flows.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • title (str) – Issue title.

  • body (str) – Optional Markdown issue body.

  • labels (list[int] | None) – Optional list of numeric label IDs to apply.

  • assignees (list[str] | None) – Optional list of assignee usernames.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with the compact summary of the created issue, or a JSON error object on API failure.

async tools.gitea_tools.gitea_update_issue(owner, repo, index, title=None, body=None, state=None, ctx=None)[source]

Update the title, body, and/or state of an existing issue.

Backs the gitea_update_issue tool. Resolves credentials via _get_credentials and PATCHes /repos/{owner}/{repo}/issues/{index} through _gitea_request with only the fields that were supplied (each None argument is omitted), returning the updated issue condensed through _fmt_issue. Setting state to closed is how issues are closed. This mutates state on the Gitea instance; locally it performs HTTP and a Redis-backed credential read only.

Registered as the gitea_update_issue handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop. It is also imported and awaited directly by tools.gitea_integration (with state="closed") to close issues from higher-level automation flows.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • index (int) – The issue’s per-repository number.

  • title (str | None) – New title, or None to leave unchanged.

  • body (str | None) – New Markdown body, or None to leave unchanged.

  • state (str | None) – New state (open or closed), or None to leave unchanged.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with the compact summary of the updated issue, or a JSON error object on API failure.

async tools.gitea_tools.gitea_list_pull_requests(owner, repo, state='open', page=1, limit=20, ctx=None)[source]

List pull requests on a Gitea repository, filtered by state.

Backs the gitea_list_pull_requests tool. Resolves credentials via _get_credentials and pages GET /repos/{owner}/{repo}/pulls through _gitea_request with the state filter, condensing each PR through _fmt_pr. Performs HTTP and a Redis-backed credential read only; no writes.

Registered as the gitea_list_pull_requests handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • state (str) – PR state filter: open, closed, or all.

  • page (int) – 1-based page number to fetch.

  • limit (int) – Results per page; values above 50 are clamped to 50.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with a count and a pull_requests array of compact PR summaries, or a JSON error object on API failure.

async tools.gitea_tools.gitea_get_pull_request(owner, repo, index, ctx=None)[source]

Fetch a single pull request by index, including a body excerpt.

Backs the gitea_get_pull_request tool. Resolves credentials via _get_credentials and requests GET /repos/{owner}/{repo}/pulls/{index} through _gitea_request, condensing the PR through _fmt_pr and then attaching the first 2000 characters of its body on top of that summary so the LLM can read the description. Performs HTTP and a Redis-backed credential read only.

Registered as the gitea_get_pull_request handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • index (int) – The pull request’s per-repository number.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with the compact PR summary plus a truncated body, or a JSON error object on API failure.

async tools.gitea_tools.gitea_create_pull_request(owner, repo, title, head, base='main', body='', ctx=None)[source]

Open a new pull request from a head branch into a base branch.

Backs the gitea_create_pull_request tool. Resolves credentials via _get_credentials and POSTs to /repos/{owner}/{repo}/pulls through _gitea_request with the title, head ref (which may be owner:branch for cross-fork PRs), base branch, and optional body, returning the created PR condensed through _fmt_pr. This mutates state on the Gitea instance; locally it performs HTTP and a Redis-backed credential read only.

Registered as the gitea_create_pull_request handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • title (str) – Pull request title.

  • head (str) – Source branch, or owner:branch when the head is on a fork.

  • base (str) – Target branch to merge into; defaults to main.

  • body (str) – Optional Markdown description; omitted when empty.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with the compact summary of the created pull request, or a JSON error object on API failure.

async tools.gitea_tools.gitea_merge_pull_request(owner, repo, index, merge_style='merge', delete_branch_after_merge=False, ctx=None)[source]

Merge a pull request using the requested merge strategy.

Backs the gitea_merge_pull_request tool. Resolves credentials via _get_credentials and POSTs to /repos/{owner}/{repo}/pulls/{index}/merge through _gitea_request with the merge strategy under Gitea’s Do key and an optional flag to delete the head branch afterwards. The supported merge_style values are merge, rebase, rebase-merge, and squash. On success it returns a fixed status object rather than the raw API body. This mutates repository state (and may delete a branch); locally it performs HTTP and a Redis-backed credential read only.

Registered as the gitea_merge_pull_request handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • index (int) – The pull request’s per-repository number.

  • merge_style (str) – Merge strategy: merge, rebase, rebase-merge, or squash.

  • delete_branch_after_merge (bool) – Whether to delete the head branch once merged.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON success object on a successful merge, or a JSON error object on API failure.

async tools.gitea_tools.gitea_get_file(owner, repo, path, ref='', ctx=None)[source]

Read a file’s contents or list a directory in a Gitea repository.

Backs the gitea_get_file tool. Resolves credentials via _get_credentials and requests GET /repos/{owner}/{repo}/contents/{path} through _gitea_request at an optional ref (branch, tag, or SHA). The Gitea contents endpoint is polymorphic, so this branches on the response: for a file it base64-decodes the embedded content (falling back to a “(binary file)” marker when decoding fails) and returns name, path, size, SHA, a truncated body, and HTML URL; for a directory it returns a list of name/type/path entries. Performs HTTP and a Redis-backed credential read only.

Registered as the gitea_get_file handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • path (str) – File or directory path within the repository.

  • ref (str) – Optional branch, tag, or commit SHA; defaults to the default branch.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string describing either a file (with decoded, truncated content) or a directory listing, or a JSON error object on API failure.

async tools.gitea_tools.gitea_list_commits(owner, repo, sha='', page=1, limit=20, ctx=None)[source]

List commits in a Gitea repository, optionally from a given ref.

Backs the gitea_list_commits tool. Resolves credentials via _get_credentials and pages GET /repos/{owner}/{repo}/commits through _gitea_request, optionally scoped to a branch or SHA. Each commit is flattened inline to its SHA, a truncated message, author name and date, and HTML URL (rather than via a shared formatter). Performs HTTP and a Redis-backed credential read only; no writes.

Registered as the gitea_list_commits handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • sha (str) – Optional branch name or commit SHA to list history from.

  • page (int) – 1-based page number to fetch.

  • limit (int) – Results per page; values above 50 are clamped to 50.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with a count and a commits array of compact commit summaries, or a JSON error object on API failure.

async tools.gitea_tools.gitea_get_commit(owner, repo, sha, ctx=None)[source]

Fetch a single commit’s metadata and stats by SHA or ref.

Backs the gitea_get_commit tool. Resolves credentials via _get_credentials and requests GET /repos/{owner}/{repo}/git/commits/{sha} through _gitea_request, returning the SHA, a truncated commit message, author name and date, HTML URL, and the diff stats block. Defensive isinstance guards keep the projection safe when the API returns an unexpected shape. Performs HTTP and a Redis-backed credential read only.

Registered as the gitea_get_commit handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • sha (str) – Commit SHA or ref to fetch.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with the compact commit summary including stats, or a JSON error object on API failure.

async tools.gitea_tools.gitea_list_notifications(all_notifications=False, page=1, limit=20, ctx=None)[source]

List the authenticated user’s Gitea notification feed.

Backs the gitea_list_notifications tool. Resolves credentials via _get_credentials and pages GET /notifications through _gitea_request; by default only unread notifications are returned, while all_notifications includes read ones. Each entry is flattened inline to its id, unread flag, subject title and type, owning repository full name, and update timestamp. Performs HTTP and a Redis-backed credential read only; no writes.

Registered as the gitea_list_notifications handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • all_notifications (bool) – Whether to include already-read notifications.

  • page (int) – 1-based page number to fetch.

  • limit (int) – Results per page; values above 50 are clamped to 50.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with a count and a notifications array of compact notification summaries, or a JSON error object on API failure.

async tools.gitea_tools.gitea_star_repo(owner, repo, star=True, ctx=None)[source]

Star or unstar a Gitea repository for the authenticated user.

Backs the gitea_star_repo tool. Resolves credentials via _get_credentials and calls /user/starred/{owner}/{repo} through _gitea_request using PUT to star or DELETE to unstar based on the star flag. On success it returns a fixed status object naming the action taken. This mutates the user’s star set on the Gitea instance; locally it performs HTTP and a Redis-backed credential read only.

Registered as the gitea_star_repo handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • star (bool) – True to star the repository, False to unstar it.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON success object describing the starred or unstarred action, or a JSON error object on API failure.

async tools.gitea_tools.gitea_list_branches(owner, repo, page=1, limit=30, ctx=None)[source]

List the branches of a Gitea repository.

Backs the gitea_list_branches tool. Resolves credentials via _get_credentials and pages GET /repos/{owner}/{repo}/branches through _gitea_request, projecting each branch to its name, protection flag, and head commit SHA. Performs HTTP and a Redis-backed credential read only; no writes.

Registered as the gitea_list_branches handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • page (int) – 1-based page number to fetch.

  • limit (int) – Results per page; values above 50 are clamped to 50.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with a count and a branches array of compact branch summaries, or a JSON error object on API failure.

async tools.gitea_tools.gitea_create_repo_from_template(template_owner, template_repo, name, description='', private=False, git_content=True, ctx=None)[source]

Generate a new repository from an existing template repository.

Backs the gitea_create_repo_from_template tool. Resolves credentials via _get_credentials and POSTs to /repos/{template_owner}/{template_repo}/generate through _gitea_request with the new repo name, privacy flag, an optional description, and a git_content flag that controls whether the template’s git history is copied. The created repo is returned condensed through _fmt_repo. This mutates state on the Gitea instance; locally it performs HTTP and a Redis-backed credential read only.

Registered as the gitea_create_repo_from_template handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • template_owner (str) – Owner of the template repository.

  • template_repo (str) – Name of the template repository.

  • name (str) – Name for the new repository.

  • description (str) – Optional description for the new repository.

  • private (bool) – Whether the new repository should be private.

  • git_content (bool) – Whether to copy the template’s git content.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with the compact summary of the generated repository, or a JSON error object on API failure.

async tools.gitea_tools.gitea_compare_commits(owner, repo, basehead, ctx=None)[source]

Compare two refs or commits and report the diff between them.

Backs the gitea_compare_commits tool. Resolves credentials via _get_credentials and requests GET /repos/{owner}/{repo}/compare/{basehead} through _gitea_request, where basehead uses Gitea’s compare syntax (e.g. main...feature); the value is URL-quoted while preserving : and . so the ... separator survives. Unlike most handlers it returns the raw API response unconditionally (wrapping non-JSON in a truncated raw field) rather than reformatting. Performs HTTP and a Redis-backed credential read only.

Registered as the gitea_compare_commits handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • basehead (str) – Compare expression in base...head form.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with the comparison result (commits and changed files), or a truncated raw payload when the response is not structured.

async tools.gitea_tools.gitea_list_tags(owner, repo, page=1, limit=30, ctx=None)[source]

List the tags of a Gitea repository.

Backs the gitea_list_tags tool. Resolves credentials via _get_credentials and pages GET /repos/{owner}/{repo}/tags through _gitea_request, projecting each tag to its name, id, tagged commit SHA, and a truncated message. Performs HTTP and a Redis-backed credential read only; no writes.

Registered as the gitea_list_tags handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • page (int) – 1-based page number to fetch.

  • limit (int) – Results per page; values above 50 are clamped to 50.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with a count and a tags array of compact tag summaries, or a JSON error object on API failure.

async tools.gitea_tools.gitea_create_tag(owner, repo, tag_name, target, message='', ctx=None)[source]

Create a tag pointing at a commit or branch.

Backs the gitea_create_tag tool. Resolves credentials via _get_credentials and POSTs to /repos/{owner}/{repo}/tags through _gitea_request with the tag name and target ref, plus an optional message that makes it an annotated tag. The Gitea instance generally requires a write:repository scope for this. This mutates repository state; locally it performs HTTP and a Redis-backed credential read only.

Registered as the gitea_create_tag handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • tag_name (str) – Name of the tag to create.

  • target (str) – Branch name or commit SHA the tag should point at.

  • message (str) – Optional annotated-tag message; omitted when empty.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with the created tag object, or a truncated raw payload when the response is not structured.

async tools.gitea_tools.gitea_list_milestones(owner, repo, state='open', page=1, limit=20, ctx=None)[source]

List the milestones of a Gitea repository, filtered by state.

Backs the gitea_list_milestones tool. Resolves credentials via _get_credentials and pages GET /repos/{owner}/{repo}/milestones through _gitea_request with the state filter, projecting each milestone to id, title, a truncated description, state, open/closed issue counts, and due date. Most Gitea instances require a read:issue scope for this. Performs HTTP and a Redis-backed credential read only; no writes.

Registered as the gitea_list_milestones handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • state (str) – Milestone state filter: open, closed, or all.

  • page (int) – 1-based page number to fetch.

  • limit (int) – Results per page; values above 50 are clamped to 50.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with a count and a milestones array of compact milestone summaries, or a JSON error object on API failure.

async tools.gitea_tools.gitea_get_milestone(owner, repo, milestone_id, ctx=None)[source]

Fetch a single milestone by its numeric id.

Backs the gitea_get_milestone tool. Resolves credentials via _get_credentials and requests GET /repos/{owner}/{repo}/milestones/{milestone_id} through _gitea_request, returning the raw milestone object (wrapping a non-JSON response in a truncated raw field). Performs HTTP and a Redis-backed credential read only.

Registered as the gitea_get_milestone handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • milestone_id (int) – Numeric milestone id.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with the milestone object, or a truncated raw payload when the response is not structured.

async tools.gitea_tools.gitea_create_milestone(owner, repo, title, description='', due_on='', ctx=None)[source]

Create a new milestone on a Gitea repository.

Backs the gitea_create_milestone tool. Resolves credentials via _get_credentials and POSTs to /repos/{owner}/{repo}/milestones through _gitea_request with the title and any supplied description and due date. The due_on value, when set, must be an ISO 8601 datetime. Creating milestones typically requires a write:issue scope on the instance. This mutates repository state; locally it performs HTTP and a Redis-backed credential read only.

Registered as the gitea_create_milestone handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • title (str) – Milestone title.

  • description (str) – Optional milestone description; omitted when empty.

  • due_on (str) – Optional ISO 8601 due date; omitted when empty.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with the created milestone object, or a truncated raw payload when the response is not structured.

async tools.gitea_tools.gitea_update_milestone(owner, repo, milestone_id, title=None, description=None, state=None, due_on=None, ctx=None)[source]

Update the fields of an existing milestone.

Backs the gitea_update_milestone tool. Resolves credentials via _get_credentials and PATCHes /repos/{owner}/{repo}/milestones/{milestone_id} through _gitea_request with only the fields that were supplied (each None argument is omitted), so it can change the title, description, state, and/or due date in one call. This mutates repository state; locally it performs HTTP and a Redis-backed credential read only.

Registered as the gitea_update_milestone handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • milestone_id (int) – Numeric milestone id.

  • title (str | None) – New title, or None to leave unchanged.

  • description (str | None) – New description, or None to leave unchanged.

  • state (str | None) – New state (open or closed), or None to leave unchanged.

  • due_on (str | None) – New ISO 8601 due date, or None to leave unchanged.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with the updated milestone object, or a truncated raw payload when the response is not structured.

async tools.gitea_tools.gitea_delete_milestone(owner, repo, milestone_id, ctx=None)[source]

Delete a milestone from a Gitea repository by id.

Backs the gitea_delete_milestone tool. Resolves credentials via _get_credentials and issues DELETE /repos/{owner}/{repo}/milestones/{milestone_id} through _gitea_request; on a no-content success it returns a small status object carrying the API detail. This permanently removes the milestone on the Gitea instance; locally it performs HTTP and a Redis-backed credential read only.

Registered as the gitea_delete_milestone handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • milestone_id (int) – Numeric milestone id to delete.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with the API response, or an ok status object when the delete returns no content.

async tools.gitea_tools.gitea_list_labels(owner, repo, page=1, limit=30, ctx=None)[source]

List the issue labels defined on a Gitea repository.

Backs the gitea_list_labels tool. Resolves credentials via _get_credentials and pages GET /repos/{owner}/{repo}/labels through _gitea_request, projecting each label to its id, name, hex color, and description. Many instances require a read:issue scope for this. Performs HTTP and a Redis-backed credential read only; no writes.

Registered as the gitea_list_labels handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • page (int) – 1-based page number to fetch.

  • limit (int) – Results per page; values above 50 are clamped to 50.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with a count and a labels array of compact label summaries, or a JSON error object on API failure.

async tools.gitea_tools.gitea_create_label(owner, repo, name, color, description='', ctx=None)[source]

Create a new issue label on a Gitea repository.

Backs the gitea_create_label tool. Resolves credentials via _get_credentials and POSTs to /repos/{owner}/{repo}/labels through _gitea_request with the label name, a hex color (any leading # is stripped so callers may pass either form), and an optional description. Creating labels typically requires a write:issue scope on the instance. This mutates repository state; locally it performs HTTP and a Redis-backed credential read only.

Registered as the gitea_create_label handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • name (str) – Label name.

  • color (str) – Hex color, with or without a leading # (e.g. e11d21).

  • description (str) – Optional label description; omitted when empty.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with the created label object, or a truncated raw payload when the response is not structured.

async tools.gitea_tools.gitea_list_issue_comments(owner, repo, index, page=1, limit=30, ctx=None)[source]

List the comments on an issue or pull request.

Backs the gitea_list_issue_comments tool. In Gitea issues and pull requests share a single numbering space, so this works for either. Resolves credentials via _get_credentials and pages GET /repos/{owner}/{repo}/issues/{index}/comments through _gitea_request, projecting each comment to its id, a truncated body, author login, and timestamps. Performs HTTP and a Redis-backed credential read only; no writes.

Registered as the gitea_list_issue_comments handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop. It is also awaited directly by gitea_list_pull_comments in this module, which is just an alias for PR comment threads.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • index (int) – The issue or pull request number.

  • page (int) – 1-based page number to fetch.

  • limit (int) – Results per page; values above 50 are clamped to 50.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with a count and a comments array of compact comment summaries, or a JSON error object on API failure.

async tools.gitea_tools.gitea_create_issue_comment(owner, repo, index, body, ctx=None)[source]

Post a comment on an issue or pull request.

Backs the gitea_create_issue_comment tool. Because Gitea shares one numbering space between issues and PRs, the same index addresses either. Resolves credentials via _get_credentials and POSTs the Markdown body to /repos/{owner}/{repo}/issues/{index}/comments through _gitea_request. This mutates state on the Gitea instance; locally it performs HTTP and a Redis-backed credential read only.

Registered as the gitea_create_issue_comment handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop. It is also imported and awaited directly by tools.gitea_integration to post comments from higher-level automation flows.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • index (int) – The issue or pull request number.

  • body (str) – Markdown comment body.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with the created comment object, or a truncated raw payload when the response is not structured.

async tools.gitea_tools.gitea_list_releases(owner, repo, draft=False, pre_release=False, page=1, limit=10, ctx=None)[source]

List the releases of a Gitea repository.

Backs the gitea_list_releases tool. Resolves credentials via _get_credentials and pages GET /repos/{owner}/{repo}/releases through _gitea_request, optionally filtering by draft and pre-release status, and projects each release to its id, tag name, name, draft/prerelease flags, timestamps, and HTML URL. Performs HTTP and a Redis-backed credential read only; no writes.

Registered as the gitea_list_releases handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • draft (bool) – Whether to include draft releases in the listing.

  • pre_release (bool) – Whether to include pre-releases in the listing.

  • page (int) – 1-based page number to fetch.

  • limit (int) – Results per page; values above 50 are clamped to 50.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with a count and a releases array of compact release summaries, or a JSON error object on API failure.

async tools.gitea_tools.gitea_get_release(owner, repo, release_id, ctx=None)[source]

Fetch a single release by its numeric id.

Backs the gitea_get_release tool. Resolves credentials via _get_credentials and requests GET /repos/{owner}/{repo}/releases/{release_id} through _gitea_request, returning the raw release object (wrapping a non-JSON response in a truncated raw field). Performs HTTP and a Redis-backed credential read only.

Registered as the gitea_get_release handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • release_id (int) – Numeric release id.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with the release object, or a truncated raw payload when the response is not structured.

async tools.gitea_tools.gitea_create_release(owner, repo, tag_name, name='', body='', target_commitish='', draft=False, prerelease=False, ctx=None)[source]

Create a release for a Gitea repository from a tag.

Backs the gitea_create_release tool. Resolves credentials via _get_credentials and POSTs to /repos/{owner}/{repo}/releases through _gitea_request with the tag name, draft/prerelease flags, and any supplied display name, body, and target commitish (which lets Gitea create the tag on the fly when it does not yet exist). The instance generally requires a write:repository or release scope. This mutates repository state; locally it performs HTTP and a Redis-backed credential read only.

Registered as the gitea_create_release handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • tag_name (str) – Tag the release is associated with.

  • name (str) – Optional display name for the release; omitted when empty.

  • body (str) – Optional Markdown release notes; omitted when empty.

  • target_commitish (str) – Optional branch or SHA to tag if the tag does not yet exist; omitted when empty.

  • draft (bool) – Whether to create the release as a draft.

  • prerelease (bool) – Whether to mark the release as a pre-release.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with the created release object, or a truncated raw payload when the response is not structured.

async tools.gitea_tools.gitea_delete_release(owner, repo, release_id, ctx=None)[source]

Delete a release from a Gitea repository by id.

Backs the gitea_delete_release tool. Resolves credentials via _get_credentials and issues DELETE /repos/{owner}/{repo}/releases/{release_id} through _gitea_request; on a no-content success it returns a small status object carrying the API detail. This permanently removes the release on the Gitea instance; locally it performs HTTP and a Redis-backed credential read only.

Registered as the gitea_delete_release handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • release_id (int) – Numeric release id to delete.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with the API response, or an ok status object when the delete returns no content.

async tools.gitea_tools.gitea_fork_repo(owner, repo, organization='', name='', ctx=None)[source]

Fork a repository into the user’s account or a chosen organization.

Backs the gitea_fork_repo tool. Resolves credentials via _get_credentials and POSTs to /repos/{owner}/{repo}/forks through _gitea_request with an optional target organization and an optional new name (an empty payload, sent as None, forks into the user’s own account). On success the new fork is condensed through _fmt_repo, while error responses are passed through unchanged. This mutates state on the Gitea instance; locally it performs HTTP and a Redis-backed credential read only.

Registered as the gitea_fork_repo handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Owner of the repository to fork.

  • repo (str) – Name of the repository to fork.

  • organization (str) – Optional organization to fork into instead of the user.

  • name (str) – Optional name for the fork; defaults to the source name.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with the compact summary of the new fork, or a JSON error object on API failure.

async tools.gitea_tools.gitea_create_branch(owner, repo, new_branch_name, old_branch_name='', old_ref_name='', ctx=None)[source]

Create a new branch from an existing branch or ref.

Backs the gitea_create_branch tool. Resolves credentials via _get_credentials and POSTs to /repos/{owner}/{repo}/branches through _gitea_request with the new branch name and, when provided, a source branch (old_branch_name) or arbitrary source ref (old_ref_name); when neither is given the instance branches from the default branch. This typically requires a write:repository scope and mutates repository state; locally it performs HTTP and a Redis-backed credential read only.

Registered as the gitea_create_branch handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • new_branch_name (str) – Name for the branch to create.

  • old_branch_name (str) – Optional source branch to branch from; omitted when empty.

  • old_ref_name (str) – Optional source ref to branch from, as an alternative to old_branch_name; omitted when empty.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with the created branch object, or a truncated raw payload when the response is not structured.

async tools.gitea_tools.gitea_delete_branch(owner, repo, branch, ctx=None)[source]

Delete a branch from a Gitea repository.

Backs the gitea_delete_branch tool. Resolves credentials via _get_credentials, URL-encodes the branch name (so names containing slashes survive), and issues DELETE /repos/{owner}/{repo}/branches/{branch} through _gitea_request; on a no-content success it returns a small status object carrying the API detail. This typically requires a write:repository scope and removes the branch on the Gitea instance; locally it performs HTTP and a Redis-backed credential read only.

Registered as the gitea_delete_branch handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • branch (str) – Name of the branch to delete.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with the API response, or an ok status object when the delete returns no content.

async tools.gitea_tools.gitea_list_wiki_pages(owner, repo, ctx=None)[source]

List the wiki pages of a Gitea repository.

Backs the gitea_list_wiki_pages tool. Resolves credentials via _get_credentials and requests GET /repos/{owner}/{repo}/wiki/pages through _gitea_request, returning the raw page index (wrapping a non-structured response in a truncated raw field). When the repository has its wiki disabled the underlying request yields a 404 error. Performs HTTP and a Redis-backed credential read only; no writes.

Registered as the gitea_list_wiki_pages handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with the wiki page list, or a truncated raw payload when the response is not structured.

async tools.gitea_tools.gitea_get_wiki_page(owner, repo, page_name, ctx=None)[source]

Fetch the content of a single wiki page by title or slug.

Backs the gitea_get_wiki_page tool. Resolves credentials via _get_credentials, URL-encodes the page name (so titles with spaces or slashes survive), and requests GET /repos/{owner}/{repo}/wiki/page/{name} through _gitea_request, returning the raw page object (wrapping a non-JSON response in a truncated raw field). Performs HTTP and a Redis-backed credential read only.

Registered as the gitea_get_wiki_page handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • page_name (str) – Wiki page title or slug to fetch.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with the wiki page object, or a truncated raw payload when the response is not structured.

async tools.gitea_tools.gitea_list_actions_tasks(owner, repo, page=1, limit=20, ctx=None)[source]

List Gitea Actions workflow runs (tasks) for a repository.

Backs the gitea_list_actions_tasks tool. Resolves credentials via _get_credentials and pages GET /repos/{owner}/{repo}/actions/tasks through _gitea_request. Because the exact response shape varies across Gitea versions, this returns the raw payload as-is (wrapping a non-dict response in a truncated raw field) rather than projecting fixed fields. Performs HTTP and a Redis-backed credential read only; no writes.

Registered as the gitea_list_actions_tasks handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • page (int) – 1-based page number to fetch.

  • limit (int) – Results per page; values above 50 are clamped to 50.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with the raw Actions tasks payload, or a truncated raw payload when the response is not structured.

async tools.gitea_tools.gitea_list_pull_comments(owner, repo, index, page=1, limit=30, ctx=None)[source]

List the comments on a pull request.

Backs the gitea_list_pull_comments tool. Because Gitea exposes pull request conversation comments through the shared issue-comment thread (PRs and issues share one numbering space), this is a thin alias that simply awaits gitea_list_issue_comments with the same arguments rather than hitting a separate review-comments endpoint. All credential resolution and HTTP happen inside that delegate; this function itself performs no I/O.

Registered as the gitea_list_pull_comments handler in this module’s TOOLS list and dispatched by name from the inference worker’s tool loop; not called directly elsewhere in the repo.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • index (int) – The pull request number.

  • page (int) – 1-based page number to fetch.

  • limit (int) – Results per page; values above 50 are clamped to 50.

  • ctx (ToolContext | None) – The active ToolContext supplying user credentials.

Return type:

str

Returns:

A JSON string with a count and a comments array of compact comment summaries, or a JSON error object on API failure.