Read a file's content from a Gitea repository.

Returns Gitea's ContentsResponse shape extended with a text field containing the decoded file content as a UTF-8 string (or None if the content isn't valid UTF-8 — binary file). The raw base64 content and Gitea's encoding are preserved so callers can re-decode if needed.

The sha field in the response is what :func:commit_changes would need to update this file — but commit_changes fetches it internally, so callers don't usually need to pass it forward.

Create a new branch in a repository.

Returns the created Gitea Branch object. Fails cleanly via :class:GiteaAPIError if the new branch name already exists.

Create or update a single file on a branch in one commit.

Auto-detects whether the file exists:

• File does not exist on the branch: Gitea returns 404 to the SHA lookup; we POST to create the file.

• File exists: we use its current SHA and PUT to update it.

Returns Gitea's FileResponse shape (the resulting commit + content metadata). Raises :class:GiteaAPIError on conflicts (e.g. concurrent update changed the SHA between our lookup and our write — caller should re-read and retry).

Single-file only. Multi-file commits would require Gitea's Git Trees API and are deliberately out of scope for this tool.

Open a new pull request from head into base.

Returns the created Gitea PullRequest object (including the assigned number, URL, and merge status). Raises :class:GiteaAPIError if the head branch doesn't exist, there are no commits between head and base, or an open PR already exists for this branch pair.

Create a new issue in a Gitea repository.

Returns the full Gitea Issue object including the assigned number, URL, and metadata. Label names are resolved to IDs against the repository's label set; an unknown label name fails the call cleanly with the list of valid names.

List issues in a Gitea repository.

Pull requests are excluded; only true issues are returned. Filters compose (state AND labels AND assignee).

Get a single issue by number, including all of its comments.

The returned object is the standard Gitea Issue payload, with an additional comments_list field containing the full list of Comment objects. The existing top-level comments integer field (comment count) is preserved.

Update an existing issue's title, body, state, assignees, milestone, or labels.

Each argument is independent — pass only the fields you want to change. Labels are replaced atomically against the new set (passing [] removes all labels). Other list fields (assignees) follow the same replace semantics.

Add a comment to an existing issue. Returns the created Comment object.

List branches in a repository.

Returns the standard Gitea Branch object array: [{name, commit: {id, ...}, protected, ...}]. Useful for inspecting available targets before creating a release, opening a PR, or filing a fix against a specific branch.

List pull requests in a repository, optionally filtered by state.

Returns Gitea PullRequest objects (not Issue-style — the PR endpoint returns richer head/base/mergeable info than the issues endpoint does even when issues are filtered to type=pulls).

Get a single pull request by number, including its discussion comments.

Mirrors :func:gitea_mcp.tools.issues.get_issue's shape: returns the full Gitea PullRequest object with an additional comments_list field containing the issue-style comment thread. Inline review comments (those attached to specific diff lines) are NOT included — those live under /pulls/{n}/reviews and are out of scope for this tool.

Add a comment to a pull request's discussion thread.

Posts to /repos/{owner}/{repo}/issues/{pull_number}/comments — Gitea's issue-comments endpoint also serves PR conversation comments (PRs and issues share the number namespace and comment infrastructure). For inline diff-line review comments, a separate /pulls/{n}/reviews-based tool would be needed; that's deliberately out of scope here.

Merge a pull request.

Calls POST /repos/{owner}/{repo}/pulls/{pull_number}/merge using the requested merge strategy and optional commit-message overrides. This is tagged destructiveHint=True because it changes repository history and closes the pull request.

List releases for a repository.

Returns the standard Gitea Release object array, including drafts and pre-releases. Sort order is newest first.

Create a new release in a repository.

.. warning::

Side effects: if tag_name does not already exist in the repository, Gitea creates the tag at the current target_commitish (or default branch). Creating a draft does NOT skip tag creation — both drafts and published releases will leave a tag in the repo.

List repositories.

Three modes:

• owner empty: returns repositories accessible to the authenticated user (GET /user/repos).

• owner is a user: returns that user's repositories (GET /users/{owner}/repos).

• owner is an organization: returns that org's repositories (GET /orgs/{owner}/repos — automatically tried as a fallback when the user endpoint 404s, so callers don't need to know which it is).

List labels defined in a repository.

Returns the standard Gitea Label object: {id, name, color, description, ...}. Use the id values when calling tools that take label_ids directly; most tools accept label names and resolve to IDs internally.

List milestones in a repository, optionally filtered by state.

Return the running gitea-mcp server's version.

No network call — just reports the package version. openWorldHint is False for this tool only, since it doesn't touch the Gitea instance or any external system.

Return information about the running gitea-mcp server and its Gitea connection.

Performs two Gitea API calls — GET /user (to identify the authenticated user the PAT belongs to) and GET /version (to report the Gitea instance version). If /version is unavailable (older Gitea, or the PAT lacks the scope), gitea_version falls back to None rather than raising.

Returns a dict with:

• gitea_mcp_version — the gitea-mcp package version (e.g. "0.4.1").

• gitea_url — the Gitea base URL this server is configured against.

• gitea_user — the login of the authenticated Gitea user.

• gitea_version — the Gitea instance version string, or None if unavailable.