Adds a comment to an issue or a pull request (shared numbering).

Parameters: owner, repo, number (required), body (string, required), response_format.

Returns: { id, author, created_at, html_url }

Write operation: requires the 'write:issue' scope. The comment is attributed to the token's owner and cannot be deleted by this tool.

Opens a new issue. Write operation: requires the 'write:issue' scope.

Parameters:

• owner, repo (optional when defaults are configured)

• title (string, required)

• body (string, optional): markdown description

• labels (string[], optional): label names; unknown names are skipped and reported

• assignees (string[], optional): login names

Returns: { number, title, state, html_url, unresolved_labels }

The issue is attributed to the token's owner — check with forgejo_whoami if unsure.

Opens a pull request between two branches of the repository. Write operation: requires the 'write:repository' scope.

Parameters:

• owner, repo (optional when defaults are configured)

• head (string, required): source branch, already pushed to the server

• base (string, required): target branch, typically 'main'

• title (string, required)

• body (string, optional)

Returns: { number, title, state, head, base, html_url }

Prerequisite: the 'head' branch must exist server-side — push before calling. Errors: 409 if a PR is already open for this branch pair; 404 if the head or base branch does not exist; 422 if the request is otherwise rejected.

Reads a text file's contents, or lists a directory, at a given revision.

Parameters:

• owner, repo (optional when defaults are configured)

• path (string, required): path from the repository root, e.g. 'lib/filters.ts'; '' or '.' for the root

• ref (string, optional): branch, tag or SHA. Defaults to the main branch

• response_format

Returns, for a file: { type: 'file', path, size, sha, content, truncated, html_url } Returns, for a directory: { type: 'directory', path, entries: [{ name, type, size }] }

Binary files are not decoded: their size and SHA are returned with an explicit note. Contents are truncated past the context limit and the cut is reported.

Returns a full issue: description, metadata and, on request, its comments.

Parameters: owner, repo, number (required), include_comments (bool, default true), response_format.

Returns: { number, title, state, author, labels, assignees, body, html_url, comments: [{ author, body, created_at }] }

Also works with a pull request number: issues and PRs share one numbering space in Forgejo. Errors: 404 if the number does not exist in this repository.

Returns a pull request: description, merge state, statistics and, on request, the unified diff.

Parameters: owner, repo, number (required), include_diff (bool, default false), response_format.

Returns: { number, title, state, merged, mergeable, head, base, additions, deletions, changed_files, body, html_url, diff? }

The diff is truncated past the context limit and the cut is explicitly reported in the returned text. Tip: leave include_diff=false for a status check — it saves a lot of context.

Lists the repository's branches with their latest commit and protection status.

Parameters: owner, repo, page, limit, response_format.

Returns: { total, count, page, limit, has_more, branches: [{ name, protected, commit_sha, commit_message }] }

Use it to confirm a branch exists before opening a pull request with forgejo_create_pull_request.

Lists a branch's commits, newest first.

Parameters: owner, repo, branch (string, optional — the repository's default branch when omitted), page, limit, response_format.

Returns: { total, count, page, limit, has_more, commits: [{ sha, message, author, date, html_url }] }

Examples:

• "what changed recently" -> limit=10

• "history of the migration branch" -> branch='birdiz/migration'

Lists a repository's issues. Pull requests are excluded (use forgejo_list_pull_requests).

Parameters:

• owner, repo (string, optional when defaults are configured)

• state ('open' | 'closed' | 'all', default 'open')

• labels (string[], optional): label names, all of them required

• query (string, optional): full-text search across title and body

• page, limit, response_format

Returns: { total, count, page, limit, has_more, issues: [{ number, title, state, author, labels, comments, created_at, updated_at, html_url }] }

Examples:

• "open issues on the CRM" -> state='open'

• "closed bugs" -> state='closed', labels=['bug']

Lists a repository's pull requests.

Parameters: owner, repo, state ('open' | 'closed' | 'all', default 'open'), page, limit, response_format.

Returns: { total, count, page, limit, has_more, pull_requests: [{ number, title, state, merged, draft, head, base, author, html_url }] }

Note: a PR closed without merging and a merged PR both report state='closed' — rely on the 'merged' field.

Lists the repositories the token can reach, most recently updated first.

Parameters: page, limit, response_format.

Returns: { total, count, page, limit, has_more, repos: [{ full_name, private, fork, default_branch, description, updated_at, html_url }] }

Use it to discover the owner/repo values to pass to the other tools when they are unknown. Errors: 403 if the token lacks the 'read:user' scope.

Changes an existing issue: state, title, body, labels or assignees. Write operation: requires the 'write:issue' scope.

Parameters:

• owner, repo (optional when defaults are configured)

• number (required)

• state ('open' | 'closed', optional): closes or reopens the issue

• title (string, optional): replaces the current title

• body (string, optional): replaces the current body — this overwrites, it does not append

• labels (string[], optional): replaces the full label set; unknown names are skipped and reported

• assignees (string[], optional): replaces the full assignee list

At least one changing field is required; omitted fields are left untouched.

Returns: { number, title, state, labels, assignees, html_url, unresolved_labels }

Examples:

• "close issue 42" -> number=42, state='closed'

• "reopen it and retitle it" -> number=42, state='open', title='…'

To add to a discussion without altering the issue, use forgejo_comment_issue instead. Also accepts a pull request number, but only its issue-side fields change — it cannot merge or close a PR's branch.

Returns the Forgejo account the token used for this call belongs to.

No parameters.

Returns: { id, login, full_name, email }

Use it to confirm a token is valid and which identity writes will be attributed to, before creating an issue or a pull request. Errors: 401 if the token is missing, expired or revoked; 403 if it lacks the 'read:user' scope.