Forgejo Toolkit

English | 中文

Forgejo Toolkit

Codeberg

A VS Code extension for Forgejo that provides a Webview-based dashboard, repository browsing, Issue / PR management, PR worktree support, and more.

Features

• Multi-instance management: add, edit, and remove multiple Forgejo/Codeberg instances. Access tokens are stored in VS Code SecretStorage.
• Dashboard panel: repository, Issue, and Pull Request lists in the VS Code sidebar, grouped by instance, with keyword search and status filters.
• Linked repositories: detects workspace git remotes (multi-remote and multi-root workspaces included) and shows linked repository cards for quick navigation.
• Repository details: README preview, recent commits, branch / tag / release management (create / delete, release attachments), and a file browser with search and file history.
• Issue / PR management: list, detail, create, edit, close / reopen, and delete; Markdown rendering, comments, attachments, labels, assignees, milestones, due dates, dependencies, reactions, subscriptions, and time tracking.
• PR review: inline review comments (single-line and multi-line) in the native diff editor with a rich-text composer; submit reviews as comment, approve, or request changes.
• PR diff and merge: changed-file list, per-commit diffs, merge status with blocking reasons, CI status checks, and merge / squash / rebase / revert support.
• PR Worktree: check out refs/pull/<index>/head into a local worktree with configurable open mode and cache directory; Start Work on Issue creates an issue branch the same way.
• Publish and create PRs: publish a local repository or branch to Forgejo, clone through the Git: Clone quick pick, and create PRs from the status bar button.
• Notifications: unread badge, background polling with toast alerts, filters, and mark-as-read. With several windows open, only one window polls and raises alerts by default (forgejoToolkit.multiWindowLease); every window still loads notifications when opened, and a window that cannot use the coordination falls back to polling on its own.
• Global search: search repositories, Issues, and PRs across instances.
• CI / Actions: run history, job logs, artifact downloads, run cancellation, and workflow dispatch with inputs.
• MCP Server: exposes your Forgejo instance to Copilot agent mode and other MCP clients with zero configuration — read-only tools for issues, PRs, Actions, and code browsing by default, plus three write tools, each behind its own setting and VS Code's per-call approval (VS Code ≥ 1.102).
• Settings export / import: export instances (optionally encrypted) and settings to JSON, and import them back with a conflict preview.
• Internationalization: supports switching between Chinese and English.
• Debug logs: optional API request logging to the Forgejo Toolkit Output Channel.

Screenshots

Onboarding	Dashboard

Repository overview	Pull request

Issue

Installation

The extension is published on the VS Code Marketplace — search for "Forgejo Toolkit" in the Extensions view and install it directly.

From a VSIX

Every version also attaches the packaged .vsix to its Codeberg release page. Install it with Extensions → ... → Install from VSIX. To build it yourself:

pnpm --filter forgejo-toolkit package

The file is written to packages/forgejo-toolkit/forgejo-toolkit-<version>.vsix.

Open VSX

The extension is also published on Open VSX — search for "Forgejo Toolkit" in the Extensions view and install it directly. VS Code uses the Marketplace by default; VSCodium and other Open VSX-based editors read this listing.

Usage

1. After installing the extension, click the Forgejo Toolkit icon in the activity bar to open the Dashboard.
2. On first use you will enter the onboarding page to configure the Forgejo instance URL and access token.
3. Browse repositories, Issues, and PRs in the Dashboard; click a repository card to open repository details.
4. On Issue / PR detail pages you can comment, edit, close / reopen.
5. On a PR detail page, click "Open in Worktree" to check out to a local worktree.

Commands

Every command except the two pull-request review-comment commands is available from the Command Palette (Ctrl+Shift+P, prefix Forgejo Toolkit); those two live in the comment and editor context menus, and several other commands also appear in editor context menus, the SCM view, or the status bar.

Command	What it does
Open Dashboard	Opens the Forgejo dashboard in the sidebar.
Open Setup Guide	Opens the first-run setup wizard.
Open Settings	Opens the extension settings view.
Refresh Instances	Re-reads the instance configuration and refreshes the dashboard.
Copy Permalink	Copies a permanent link to the current file or selection (also in the editor context menu).
Publish to Forgejo	Publishes the current repository to your instance (also in the SCM view).
View Log	Opens the "Forgejo Toolkit" output channel.
Create PR from Current Branch	Creates a pull request from the current branch (also in the status bar).
Add Pull Review Comment	Adds a review comment on the current diff line (also in the diff editor's line context menu).
Delete Review Comment	Deletes the review comment under the cursor.
Copy MCP Config for Agents Window	Writes or copies a ready-to-use MCP config for the Agents window (user-level mcp.json, workspace .vscode/mcp.json, or clipboard; see MCP Server).
Write Copilot Instructions	Writes (or updates) a short Forgejo section in the linked repository's .github/copilot-instructions.md; the rest of the file is never touched.
Copy Polling Diagnostics	Copies a redacted JSON report of this window's notification polling and lease state to the clipboard, for bug reports.

Compatibility

• Forgejo ≥ 16.0 — the minimum is v16 because several shipped features rely on endpoints that first appeared there (Actions run jobs/artifacts/job logs/cancel/delete and multi-line review comments). Older instances may partially work but are not supported: the extension shows a warning once per instance version across windows and keeps every feature enabled, so v15 users will see request failures on those panels — a bare 404 from the server (see KNOWN_ISSUES).
• Gitea is not supported — the extension targets Forgejo (≥ 16.0), not Gitea: a Gitea instance reports a 1.x version, which falls below that floor, so requests the two platforms do not share fail rather than degrade (see the "Gitea is not supported (the extension requires Forgejo 16.0 or newer)" entry in KNOWN_ISSUES.md).
• Primary target: Forgejo v16.x — the extension is developed and validated against the latest Forgejo stable release (currently the v16 series); the minimum and the validation target are the same series.
• VS Code ≥ 1.102 — enforced via the extension's engines.vscode field.
• Multiple VS Code windows — notification polling is coordinated between windows: only one window polls and raises alerts at a time, and the job moves to the window you are working in (forgejoToolkit.multiWindowLease, on by default). Every window still loads notifications when you open the view, and a window that cannot use the coordination polls on its own.
• The Actions 1.19 floor sits below the supported minimum — the Actions API first appeared in Forgejo 1.19 and the extension compares the probed server version against that floor: a server older than 1.19 is refused with a localized "This feature requires Forgejo 1.19.0 or newer, but this server reports version <version>." error instead of a bare 404. Every version from the 1.21 era onward, including the modern v7–v16 series, compares above 1.19 — the gate can only fire for 1.18 and older — so on a Forgejo 15 instance it never fires and the Actions sub-endpoints missing there answer with the server's own 404 (see KNOWN_ISSUES). The Actions UI itself stays visible; it is the request that is refused. A server whose version cannot be probed is never blocked (the gate fails open).
• Future endpoints from newer Forgejo releases (e.g. the v17 rerun API) are gated per feature the same way and do not raise the overall minimum version either.

MCP Server (AI Agent Integration)

The extension ships a built-in MCP server that lets AI assistants — such as Copilot agent mode — query your Forgejo instance in natural language.

• Zero configuration: every configured Forgejo instance that has a stored access token is automatically exposed to MCP clients as its own server via VS Code's contributes.mcpServerDefinitionProviders API, so an agent can reach several instances in the same session. No extra setup, no separate server to run.
• Requirements: VS Code ≥ 1.102 and at least one configured instance with an access token. If neither is available, the server is simply not registered.
• Turning it off: forgejoToolkit.mcpEnabled (on by default) owns the whole surface. With it off, no server definitions are registered, the workspace-repository mapping, the instance registry and the stable-path shim are not maintained (and are stopped at once if the setting is turned off while a window is running), and the local broker is stopped, so a statically configured client cannot reach this host either. The setting applies immediately — no window reload is needed — but a client that is already connected keeps the server process VS Code spawned for it until you reload the window: the extension never owned that process.
• Usage: open Copilot chat in agent mode and ask in natural language, e.g. "list my issues" or "show the CI log of the latest failed run in this repo".
• Repository context: the Forgejo Toolkit: Write Copilot Instructions command writes a short, clearly delimited section into the linked repository's .github/copilot-instructions.md naming <instance>/<owner>/<repo> and the read-only forgejo-toolkit tools, so an agent knows which repository this workspace maps to. It creates the file when it is missing, appends its own section to an existing file, and updates that section in place when the mapping changes — the rest of the file is preserved byte for byte, and nothing is written when no configured instance matches the workspace.
• Proxy: requests honour the editor's http.proxy setting, which wins over the environment's HTTPS_PROXY / HTTP_PROXY / ALL_PROXY (each name is read in either case), and the setting is forwarded to the MCP server process as FORGEJO_MCP_PROXY.
• Tool overview: 33 tools in five groups —
  • Core: issues, pull requests, timelines, notifications, repository info, and search (e.g. list_issues, get_pull_request).
  • Actions: run history, run jobs, job logs, CI failure summaries, and artifacts (e.g. list_action_runs, get_action_run_jobs, get_action_job_log, get_ci_failure_summary).
  • Code reading: file contents and directory listings, repository file search, branches, tags, commits, file history, and PR diffs (e.g. list_repo_contents, get_file_content, search_repo_files, get_pr_diff).
  • Review & metadata: the one-call PR review brief, PR reviews, releases, labels, milestones, and your own repositories (e.g. get_pr_review_brief, list_pull_reviews, whoami).
  • Write tools (off by default, each behind its own setting): create_issue_comment adds one issue or pull request comment, submit_pull_review submits a pending pull request review as COMMENT, APPROVED or REQUEST_CHANGES, and cancel_action_run cancels a pending or running Actions workflow run. See Security below for the two gates.
• Security:
  • The 30 read tools are strictly read-only (readOnlyHint) — with them alone the agent cannot modify anything on your instance.
  • Because they are read-only, VS Code runs them without a per-call confirmation prompt. The tool surface is what keeps the agent in bounds: every read tool maps to a GET endpoint (the one exception, get_workspace_repository, only reads a local state file the extension publishes), and every input that becomes part of a request path is validated (owner, repo, file paths) so a crafted argument cannot reach another endpoint.
  • The three write tools are the exception, and they are gated twice: they declare no readOnlyHint, so VS Code asks you to confirm every call (and lets you edit the parameters there), and each one also needs its own extension setting turned on — forgejoToolkit.mcpWriteTools.createIssueComment, forgejoToolkit.mcpWriteTools.submitPullReview or forgejoToolkit.mcpWriteTools.cancelActionRun, all off by default and independent of each other. A session the extension host did not establish (no broker, or a launch that only carries a token from your own configuration file) can read but never write: the call comes back as a plain refusal naming the setting to turn on, not as an error. All three support dryRun (report the plan, send nothing) and an idempotencyKey (a retry with the same key replays the earlier result instead of writing twice), and every call leaves an audit record that names the caller, instance, repository, target, tool, body size and SHA-256, result and duration — never the text. cancel_action_run is the one that stops work rather than appending text: its request has no body, so its record carries no size or digest at all, and its result says the server accepted the cancel rather than claiming the run was cancelled — the run's state is what list_action_runs reports.
  • Your token never leaves the extension host: it is read from SecretStorage and used there. The standard-mcp.json-shaped server definitions this extension provides deliberately carry no token — VS Code persists every registered definition, environment included, in the profile's workspace storage, so a token in one would be a secret at rest in cleartext. Instead, the server process VS Code spawns for a definition is a local forwarder into a broker inside the extension host, where the tools run with the token; the forwarder proves it is a same-user local process with a per-launch handshake secret. A launch you configure yourself may still put a token in its own env (your file, your choice), and that path works exactly as before.
  • The definitions therefore need that broker: if it is not reachable, the extension publishes none of them and says so in the log, rather than registering a server that would answer anonymously while the client believed it was authenticated. The static mcp.json route keeps its own documented degradation (anonymous, public-data-only reads when no window is running).
  • Large response fields and oversized results are truncated to protect the agent's context window.
  • Adding or removing instances re-resolves the exposed server automatically.
  • The server makes no model calls of its own (no MCP sampling), so VS Code's per-server "Configure Model Access" menu entry — shown for every MCP server — has no effect on it.

Using the server in the Agents window (or any static mcp.json host)

The server definitions above are contributed by the extension, and VS Code does not resolve extension-contributed MCP servers in Agents window (Agent Host) sessions — a platform limitation. To use the server there, register it through a static MCP configuration pointing at the shim the extension maintains in its globalStorage:

{
  "servers": {
    "forgejo": {
      "command": "node",
      "args": ["%APPDATA%\\Code\\User\\globalStorage\\cpf23333.forgejo-toolkit\\mcp-server.js"]
    }
  }
}

The globalStorage directory differs per platform: %APPDATA%\Code\User\globalStorage\cpf23333.forgejo-toolkit on Windows, ~/Library/Application Support/Code/User/globalStorage/cpf23333.forgejo-toolkit on macOS, ~/.config/Code/User/globalStorage/cpf23333.forgejo-toolkit on Linux (Insiders builds use Code - Insiders instead of Code).

Three files can carry this snippet, and different consumers read them:

• <profile>/User/mcp.json (recommended) — VS Code's user-level MCP registry: applies to every workspace of the profile, and VS Code forwards it to Agent Host sessions.
• .vscode/mcp.json inside a workspace — VS Code reads it for that workspace only and forwards it the same way.
• .mcp.json at the workspace root — read natively by the Agent Host only: VS Code itself ignores it ("Cannot start unknown MCP server customization"), and sessions with worktree isolation never see it, because the session workspace is the isolated worktree, not your checkout.

The easiest way to write one is the Forgejo Toolkit: Copy MCP Config for Agents Window command — it merges the snippet into the user-level mcp.json or the workspace .vscode/mcp.json, or copies it to the clipboard. Either way the path is the shim mcp-server.js, not the real server bundle: the extension rewrites the shim on every activation to point at the current installation, so the configuration survives extension upgrades (the versioned cpf23333.forgejo-toolkit-<version> install path it replaces would not).

No environment variables are needed: the server discovers the extension's published instance registry on its own and picks the instance by matching the session workspace's git remote, falling back to the most recent workspace state file the extension published when the working directory matches nothing (the working directory is decided by the session's workspace, not by the config file). Without a FORGEJO_MCP_TOKEN in env, and with no extension window running, it reads anonymously — only public data is visible. The zero-configuration variant contains no secrets, but as a general rule don't commit a workspace mcp.json into git: machine-specific absolute paths (and tokens, if you ever add an env block) don't belong in the repository.

Authenticated without a token in the config (broker mode): while the extension is running in any window with its MCP feature enabled (forgejoToolkit.mcpEnabled, on by default), the statically launched server does not stay anonymous — it transparently forwards into a local broker inside the extension host (a named pipe on Windows, a unix socket elsewhere), where the real tools run with the token. Your token never leaves the extension process and never lands in the mcp.json file; a per-launch handshake secret published in the extension's globalStorage (readable only by your own user) is what authorizes the forwarder. When no extension window is running, the same static configuration still works — it just falls back to anonymous, read-only access. Nothing to configure either way.

Known Limitations

See KNOWN_ISSUES.md (English) and KNOWN_ISSUES.zh.md (Chinese).

Main limitations:

• PR attachments must be fetched from the Issue API.
• The multi-file diff editor does not show M/R badges for modified / renamed files.
• Forgejo's PR files API may omit deleted files (the extension uses the compare API to work around this).
• Lists stop at 500 items, and only some views (issues, pull requests, comments, changed files, commits, refs, file search, MCP results) report that a list was cut off.

Development

This is a pnpm workspace monorepo.

Package Structure

Package	Description
packages/forgejo-toolkit	VS Code extension host.
packages/shared	Shared request client and common types.
packages/forgejo-api	API client generated from the Forgejo OpenAPI specification.
tools/*	Workspace tooling; currently the isolated UI-review harness (ui-review).

Tech Stack

• Extension host: TypeScript + Rolldown (ESM)
• Webview UI: Vue 3 + Vite 8 + @vscode-elements/elements
• Package management: pnpm workspaces

Common Commands

# Install dependencies
pnpm install

# Build all packages
pnpm run build

# Type check
pnpm run check

# Run tests
pnpm --filter forgejo-toolkit test
pnpm --filter @cpf23333-forgejo-toolkit/shared test

# Development mode
pnpm run dev

Open the packages/forgejo-toolkit directory in VS Code and press F5 to launch the Extension Host.

Packaging

pnpm --filter forgejo-toolkit package

The generated .vsix file is located in packages/forgejo-toolkit/.

Version Management

This project uses Changesets to manage monorepo versioning.

# After finishing a feature, record the change
pnpm run changeset

# When preparing a release, update versions and CHANGELOG automatically
pnpm run version-packages

pnpm run release is used for npm package publishing; the VS Code extension itself is packaged into a .vsix via pnpm --filter forgejo-toolkit package.

Changesets writes the per-package packages/forgejo-toolkit/CHANGELOG.md; the root CHANGELOG.md is the curated, user-facing changelog and the source of the Codeberg release notes, so it is written by hand and kept in step with the packaged copy (see docs/release.md).

Project Status

This is a personal side project. Features are tested only lightly, so bugs and edge cases are expected. Please open an issue if you run into any problems.

Feedback & Contributions

Bug reports, feature requests, pull requests, documentation improvements, and any other feedback are welcome.
If you have ideas for better interactions, layouts, workflows, or anything else, feel free to open an issue or start a discussion.

License

MIT