List issues in one Gitea repository. Paginated: page is 1-based, limit <= 100; keep paging until a page returns fewer than limit. Filters: state (default open), labels (comma-separated NAMES). RISK: Gitea may include pull requests here; to list only issues use search_issues with type='issues'. Example: list_issues({ state: 'open', page: 1, limit: 50 })

Fetch one issue by its index — the number shown in the issue URL (e.g. #42), NOT the internal id. Use to read the full body, labels, assignee, or milestone of a single issue.

Create an issue. title is required. labels takes label IDs (numbers) — call list_labels first to map names to IDs, or add labels by name after creation via add_issue_labels. assignees is an array of usernames. Returns the created issue including its number.

Update one issue by index (PATCH: only provided fields change). RISK: passing labels REPLACES the entire label set (give the full desired ID list) — to change a single label use add_issue_labels/remove_issue_label instead. state is 'open' or 'closed'; set milestone by ID.

PERMANENTLY delete an issue by index. IRREVERSIBLE (no recycle bin) and may fail if the instance disallows deletion. Confirm the index with the user first; prefer update_issue({ state: 'closed' }) to close instead of delete.

Search issues (and pull requests) across ALL repositories the token can see, by keyword/type/state/labels. Use for 'find issues about X' or duplicate detection across repos; set type='issues' to exclude pull requests. For listing one repo's issues use list_issues instead.

List comments on one issue by its index. RISK: returns only the server's DEFAULT first page (this tool exposes no pagination), so long threads may be TRUNCATED — do not assume a short list means few comments. Gitea returns oldest-first. Each comment has an id (used to update/delete it), body (Markdown), user, and timestamps.

Add a comment to an issue by its index. body is required and supports Markdown. Returns the comment including its id — retain it to later update_comment/delete_comment that exact comment.

Edit a comment by its id (NOT the issue index — get the id from list_comments). body is the full replacement Markdown. Only the comment author or a repo admin may edit (403 otherwise).

Delete a comment by its id (NOT the issue index — get the id from list_comments). IRREVERSIBLE. Confirm with the user first; only the author or a repo admin may delete (403 otherwise).

List labels in a repo. Paginated (page 1-based, limit <= 100); page until a page returns fewer than limit. Each label has id (number), name, color (hex), description. ALWAYS call this before any label mutation — label endpoints mix names and ids (add/replace use NAMES, remove/update/delete use IDS).

Create a label. name required and MUST be unique in the repo (a duplicate -> conflict error). color is 6-digit hex, with or without a leading '#' (e.g. '#ff0000' or 'ff0000'). description optional. Returns the label with its id.

Update a label by id (number — NOT the name). Provide any of name/color/description (PATCH semantics). color is 6-digit hex. Get the id from list_labels.

Permanently delete a label by id (number — NOT the name). IRREVERSIBLE and also removes it from EVERY issue that currently has it. Get the id from list_labels and confirm with the user before deleting.

Add labels to an issue by its index. labels is an array of label NAMES (strings) — NOT ids. Get valid names from list_labels; a name that does not exist errors (404). ADDITIVE: existing labels are kept. Duplicate names (both within the input and against labels already on the issue) are filtered out automatically — only labels not yet present are added.

Remove ONE label from an issue. Takes the label id (number) — NOT the name. Get the id from list_labels (issue labels carry their id). Errors if the label is not currently on the issue.

REPLACE the issue's ENTIRE label set. labels is an array of label NAMES. Every existing label is removed and ONLY the listed ones remain. Read current labels first if any must survive; confirm with the user before replacing.

Remove ALL labels from an issue by its index. Destructive for that issue's labels. Confirm with the user first; if a known subset must remain, use replace_issue_labels with that subset instead.

List the issues that BLOCK this issue (its 'blocked by' dependencies). Paginated: page is 1-based, limit <= 100; keep paging until a page returns fewer than limit. Returns 404 if the repo has not enabled issue dependencies (enable_issue_dependencies). Use list_issue_blocks for the reverse direction (issues this issue blocks).

Make an issue depend on (be blocked by) another issue. index is the issue that gains the dependency; dep_index is the blocker. dep_owner/dep_repo default to the same repo but may point at another repo (requires the instance to enable AllowCrossRepositoryDependencies). Returns the target issue (the dependent one).

Remove a dependency so index is no longer blocked by dep_index. dep_owner/dep_repo default to the same repo. Returns the target issue (the formerly dependent one). 404 if dependencies are not enabled on the repo.

List the issues that are BLOCKED BY this issue (its 'blocking' dependents). Paginated: page is 1-based, limit <= 100; keep paging until a page returns fewer than limit. Reverse direction of list_issue_dependencies (which lists the issues that block this one).

Make an issue block another issue. index is the blocker; dep_index becomes blocked by (dependent on) index. dep_owner/dep_repo default to the same repo but may point at another repo (requires AllowCrossRepositoryDependencies). Returns the blocker issue.

Remove a block so index no longer blocks dep_index. dep_owner/dep_repo default to the same repo. Returns the blocker issue. 404 if dependencies are not enabled on the repo.

Check whether an issue is blocked — i.e. has at least one dependency that is not yet closed (state !== "closed"). Returns a single structured verdict: blocked, blockers (the open dependency issues), total_dependencies, and open_blockers. A convenience aggregator over list_issue_dependencies that paginates internally (no page/limit input). Returns 404 if the repo has not enabled issue dependencies (enable_issue_dependencies).

List milestones in a repo. Paginated (page 1-based, limit <= 100). RISK: Gitea's DEFAULT returns only OPEN milestones — pass state='all' or 'closed' if you need closed/completed ones. Each milestone has id, title, state, open_issues, closed_issues, due_on.

Fetch one milestone by id (the internal id from list_milestones, NOT the title). Returns progress counts (open_issues / closed_issues), description, state, and due_on.

Create a milestone. title required. description optional. due_on optional ISO 8601 (e.g. '2025-12-31T23:59:59Z'). New milestones start in state 'open'. Returns the milestone with its id.

Update a milestone by id (PATCH: only provided fields change). Provide any of title/description/due_on/state. state is 'open' or 'closed'. NOTE: closing a milestone does NOT close its open issues (they stay open, merely ungrouped) — close the issues separately if required.

Permanently delete a milestone by id. IRREVERSIBLE. Issues assigned to it are NOT deleted — they keep existing but lose the milestone assignment (milestone becomes null). Confirm with the user first; prefer update_milestone({ state: 'closed' }) to preserve history.

List a repository's topics (tags). Returns the topic name list for the repo — useful to inspect classification before editing. Topic names are lowercase letters, digits, and hyphens. Paginated (page 1-based, limit <= 100).

REPLACE a repository's ENTIRE topic set. topics is the full list of topic names that should remain after the call — every existing topic not listed is removed. Pass an empty array to clear all topics. Topic names: lowercase letters, digits, and hyphens, starting with a letter/digit. Read current topics with list_topics first if any must survive; confirm with the user before replacing.

Add ONE topic to a repository by name. Idempotent: adding an existing topic does not error. Topic name: lowercase letters, digits, and hyphens, starting with a letter/digit. To add several topics at once or to set the exact desired set, prefer replace_topics.

Remove ONE topic from a repository by name. No error if the topic is not currently on the repo (idempotent delete). Topic name: lowercase letters, digits, and hyphens, starting with a letter/digit. Confirm with the user first.

List pull requests in one Gitea repository. Paginated: page is 1-based, limit <= 100; keep paging until a page returns fewer than limit. Filters: state (default open), labels (comma-separated NAMES), sort, milestone. Example: list_pull_requests({ state: 'open', page: 1, limit: 50 }). Cross-repo PR search uses search_issues({ type: 'pulls' }).

Fetch one pull request by its index — the number shown in the PR URL (e.g. #42), NOT the internal id. Returns the full PR including base/head branches, mergeable status, merged flag, labels, and milestone.

Create a pull request. title, head (source branch), and base (target branch) are required. For cross-fork PRs use 'owner:branch' in head. labels takes label IDs (numbers) — call list_labels first. Prefix the title with WIP: or [WIP] to prevent accidental merge while work is in progress. Returns the created PR including its number.

Update one pull request by index (PATCH: only provided fields change). Set state to 'closed' to close a PR WITHOUT merging (reopens with 'open'). RISK: passing labels REPLACES the entire label set (give the full desired ID list); base retargets the PR and is rarely reversible. To change a single label use add_issue_labels/remove_issue_label (PR #N == Issue #N — label endpoints are shared).

Merge a pull request by index. Do selects the strategy: 'merge' (merge commit), 'squash' (single commit), 'rebase' (rebase + fast-forward), 'rebase-merge' (rebase + merge commit). Optional MergeTitleField/MergeMessageField customize the merge commit; SHA guards against branch drift. IRREVERSIBLE — confirm the index, strategy, and that the PR is mergeable (get_pull_request mergeable: true) with the user BEFORE merging. Check is_pull_merged first if unsure.

Check whether a pull request has been merged. Returns a boolean (true = merged, false = not merged). Call before merge_pull_request to avoid a redundant attempt, or to confirm a PR's final state.

List the commits in one pull request by its index. Paginated (page 1-based, limit <= 100). Each entry has sha, html_url, the commit message, and an optional author. Useful for reviewing what a PR changes before merging.

List the files changed in one pull request by its index. Paginated (page 1-based, limit <= 100). Each entry has filename, status (added/modified/deleted/renamed), additions, deletions, changes, and html_url. Use to understand a PR's diff scope before reviewing or merging.

List Gitea Actions workflow runs in one repository. Paginated: page is 1-based, limit <= 100; keep paging until a page returns fewer than limit. Filters: branch, event (push, pull_request, schedule, etc.), status (pending, queued, waiting, in_progress, running, success, failure, skipped, cancelled), actor (username that triggered the run), head_sha. The response is a wrapper object { workflow_runs: [...], count: number } — the runs live under the workflow_runs key, NOT at the top level. Use this to find a run's id before calling get_action_run, cancel_action_run, or rerun_action_run.

Fetch one Actions workflow run by its runId (the numeric run ID from list_action_runs or the Gitea web UI — NOT the workflow name or index). Returns the full run including status, conclusion, head_branch, head_sha, event, started_at, completed_at, and actor. Call this BEFORE cancel_action_run (to verify the run is still active) or rerun_action_run (to verify it has completed and is rerunnable).

Cancel one Actions workflow run by runId. Only valid on runs that are still ACTIVE (status: queued, waiting, in_progress, running, pending) — cancelling an already-completed run returns an error. PARTIALLY DESTRUCTIVE: active jobs are killed and their partial results are discarded. ALWAYS call get_action_run first to confirm the run is still active, and confirm the runId with the user before cancelling. The run's conclusion becomes 'cancelled' after a successful cancel.

Rerun an entire Actions workflow run by runId. Only valid on runs that have COMPLETED (status: success, failure, cancelled, skipped) — rerunning an active run returns an error. Requires Gitea 1.26.0+. Creates a NEW run (incrementing run_attempt); the original run is not modified. ALWAYS call get_action_run first to confirm the run has completed, and confirm the runId with the user before rerunning. To rerun ONLY the failed jobs instead of the whole run, use rerun_action_run_failed_jobs.

Rerun ONLY the failed jobs of an Actions workflow run by runId. More efficient than rerun_action_run when most jobs succeeded and only a subset failed. Only valid on completed runs. Requires Gitea 1.26.0+. ALWAYS call get_action_run first to confirm the run has completed and has failed jobs (conclusion: failure), and confirm the runId with the user before rerunning.

List releases in one Gitea repository. Paginated: page is 1-based, limit <= 100; keep paging until a page returns fewer than limit. Optional filters: draft (true = drafts only, false = published only) and prerelease (true = prereleases only, false = stable only). Each release carries id (used by get_release/update_release/delete_release), tag_name, name (title), body (release notes), draft, prerelease, and attachments. Example: list_releases({ page: 1, limit: 50 })

Fetch one release by its numeric id (NOT the tag name — get the id from list_releases). Returns the full release including the title (name), release notes (body), tag_name, draft/prerelease flags, target_commitish, and attachments. Use get_release_by_tag to look up a release when you only know the tag name.

Fetch one release by its tag name (e.g. 'v1.2.0'). Useful when you only know the Git tag, not the numeric release id. Returns the same release shape as get_release; the response includes the id needed for update_release/delete_release.

Create a release. tag_name is required (the Git tag, e.g. 'v1.2.0'); the tag is created if it does not exist. name is the human-readable title; body is the release notes (Markdown). target_commitish (branch or SHA) controls where the tag points (defaults to the repo's default branch). draft and prerelease are optional booleans. Returns the created release including its numeric id.

Update one release by numeric id (PATCH: only provided fields change). Edit name (title), body (release notes), toggle draft/prerelease, retarget via target_commitish, or rename the tag via tag_name. tag_name renames the underlying Git tag — use with care. Publish a draft by setting draft=false. Get the id from list_releases or get_release_by_tag first.

PERMANENTLY delete a release by its numeric id (NOT the tag name). IRREVERSIBLE. Depending on Gitea configuration the underlying Git tag may or may not be deleted too. Confirm the id with the user first; prefer update_release({ draft: true }) to unpublish without deleting.

Edit ONE repository's metadata (PATCH: only provided fields change). Provide any of name/description/website/private/default_branch. Use description to change the repo description (pass an empty string to clear it). NOTE: name RENAMES the repo and changes its URL — confirm with the user first. Returns the updated repository.

List all wiki pages in one Gitea repository (metadata only: title, html_url, sub_url, last_commit — no page content). Paginated: page is 1-based, limit <= 100; keep paging until a page returns fewer than limit. Requires the repo's wiki feature to be enabled (404 otherwise). Example: list_wiki_pages({ page: 1, limit: 50 })

Fetch one wiki page by its pageName — the page title as it appears in the wiki URL (e.g. 'Home', 'Getting-Started'). Returns the full page with content DECODED to plain Markdown (the API's base64 is handled for you), plus footer, sidebar, commit_count, and last_commit. Use list_wiki_pages first if you are unsure of the exact page name.

Create a wiki page. title is required ('Home' is the wiki landing page; '_Sidebar' / '_Footer' are the layout pages). content is plain Markdown — base64 encoding is handled for you. message is an optional commit message. RISK: fails if a page with that title already exists — call list_wiki_pages or get_wiki_page first and use update_wiki_page for existing pages. Returns the created page with decoded content.

Edit an existing wiki page by pageName (PATCH: only provided fields change). content is plain Markdown (base64 handled for you); omit it to keep the current content. RISK: passing title RENAMES the page, which breaks existing links to the old name. Read the page with get_wiki_page first if it may have changed since your last read. Returns the updated page with decoded content.

PERMANENTLY delete a wiki page by pageName. The page is removed from the wiki; its history survives only in the wiki git repository (clone .wiki.git to recover), so treat this as IRREVERSIBLE from the API. Confirm the pageName with the user first; prefer update_wiki_page to blank or redirect a page instead of deleting it.

List the revision history of one wiki page by pageName (newest first). Returns { commits: [{ sha, message, author, commiter }], count }. Paginated: page is 1-based; keep paging while a page returns a full page of commits. Use to audit who changed a page and when, before reverting or summarizing changes.

List repository project boards (kanban). PLACEHOLDER: always returns an empty list because Gitea does not yet ship a REST API for project boards (go-gitea/gitea#36824). No HTTP request is made. The contract is stable so planning workflows can ask about projects without breaking; wiring the real endpoint will be a transparent change once the upstream API lands.

Fetch one repository project board (kanban) by id. PLACEHOLDER: always reports not-found (HTTP 404 semantics) because Gitea does not yet ship a REST API for project boards (go-gitea/gitea#36824). No HTTP request is made. The contract is stable so workflows can attempt to look up a project without breaking; the real endpoint will be wired transparently once the upstream API lands.

Detect baseUrl/owner/repo from a git repository's remotes (SSH or HTTPS). Reads upstream first, then origin, then any other remote; all discovered remotes are returned. path defaults to the current directory. Call ONCE at the start of a session to establish owner/repo for later calls instead of guessing. Errors if no parseable remote is found.

List repositories the authenticated token's user can access (across ALL owners/orgs). Paginated (page 1-based, limit <= 100). Each repo object is large — keep limit modest. Use to DISCOVER owner/repo values or find where to work, not to list one repo's issues.

Configure the Gitea connection at runtime (session-scoped, never persisted). Accepts base_url, owner, repo, and/or username — at least one is required. Providing base_url or username triggers credential re-discovery from the existing three sources (.git/config [gitea] section, GITEA_TOKEN env, git credential store). Tokens never pass through this tool; they are always read from the local credential sources. username strictly filters credential-store entries by exact match (no fallback to other identities). Use this when the server started unconfigured or when you need to switch instances/identities mid-session.

Report the resolved connection and credential state: whether the server is configured, the current baseUrl, every discovered credential candidate (source, schemes, status, masked username, secretPresent boolean), and the session-scoped target (owner, repo, username). Secrets are NEVER returned. Use this when a tool returns 401/403 or NotConfiguredError to diagnose the connection state. Takes no input.