Gitea for VSCode

Monitor Gitea Actions and pull requests without leaving your editor.

The extension works in Visual Studio Code 1.105 or later, and in other VS Code compatible editors such as Cursor, VSCodium, and Windsurf.

Install

In Visual Studio Code, Cursor, or Windsurf, search the Extensions view for Gitea for VSCode and install gitea.gitea-for-vscode from the Visual Studio Marketplace.

On VSCodium or when you need a specific build, install the .vsix from the repository releases.

Workflow, artifact, and pull request features need a Gitea instance with those APIs enabled. The extension is tested against Gitea 1.27.

Features

• A focused Current Branch view with that branch's pull request and runs
• A Workflows view grouped by the workflow names reported by Gitea, with a safe Recent runs fallback for older servers
• A multi-instance Settings view for tokens, connection checks, secrets, and variables
• Inline pull request review comments, including adding a new review comment from the editor context menu
• A dedicated Pull Requests view with one-click diff review and Approve / Request changes / Comment actions
• Jobs and step logs with one click
• Re-run a workflow run, only its failed jobs, or a single job
• Download workflow artifacts from the tree (context menu); double-click an artifact to open it in the editor (or be prompted to download first)
• Secrets and variables management
• Adaptive polling (fast when active, slower when idle)
• Status bar summary for running and failed runs

Quick Start

1. Install the extension as described above.
2. Open the Gitea for VSCode activity bar view.
3. In Settings, either set a personal access token or select Sign In with OAuth, then click Test Connection.

The default instance is https://gitea.com. Change gitea-for-vscode.baseUrl for a different default server, or add further servers in the Settings view.

To use more than one Gitea server, keep baseUrl as the default server and add the others to gitea-for-vscode.instances. The extension matches workspace remotes to their server and keeps each server's token separately in VS Code SecretStorage.

You can add an instance without editing JSON: open the extension’s Settings view, expand Gitea Instances, and select Add Gitea Instance. After entering the URL, choose Sign In with OAuth, Enter personal access token, or Skip for now. Configured URLs stay visible in that list; use its inline Sign In with OAuth action to authenticate later or replace its credential.

OAuth sign-in uses Gitea's built-in Tea application and a local PKCE callback.

Required Gitea Token Scopes

Use a personal access token with scopes that allow:

• Reading repositories
• Reading issues and pull request timelines
• Reading Actions runs, jobs, and artifacts
• Writing Actions, if you want to re-run runs or jobs
• Reading pull requests; write access to pull requests is required to add review comments from the editor
• Managing secrets/variables if you want to use the Settings view for those actions

If you do not plan to re-run runs or manage secrets or variables, you can use a read-only token.

Re-running Runs and Jobs

Right click a run to Re-run it or to re-run just its failed jobs, and a job to re-run that job alone. All three appear only where Gitea would accept them: re-run needs a finished run, and re-run failed jobs needs a run that actually failed.

There is deliberately no Cancel: Gitea exposes no API endpoint for cancelling a run (verified through 1.27.2), so it can only be done from the Gitea web UI. Deleting a run is likewise not offered.

How It Works

• Discovers repositories from your workspace git remotes or API (based on discovery mode).
• Polls for workflow runs and pull requests using an adaptive refresh interval.
• Loads jobs, steps, artifacts, secrets, and variables only when you expand a node.
• Uses the built-in SecretStorage to keep your token off disk.

Tree Views

Workflows

Shows all runs grouped by the workflow name provided by Gitea. If an instance does not provide workflow names, its runs appear in a flat Recent runs fallback instead of being labelled with misleading local guesses.

Current Branch

Shows workflow runs for your current branch only (when the repo is from your workspace). An open pull request for that branch is shown above its runs. Use the branch filter (toolbar or context menu on the repo) to view another branch or all branches. Expand a run to load jobs and steps on demand; failed jobs and steps are shown first. Under Artifacts, use the row buttons or context menu to Download or Open in browser; double-click an artifact to open the file in the editor if already downloaded, or see "Download the artifact first" otherwise.

Existing review comments are shown inline for the current branch. To add a new review comment, right click a line in a file on a branch with an open pull request and run Gitea: Add Review Comment.

Pull Requests

Lists open pull requests across discovered repositories. Expand a pull request to see its changed files. Select a pull request or file to open a native VS Code diff editor for that file. Use the pull request context menu to open it in the browser, checkout its head branch, submit an overall review as Approve, Request changes, or Comment, merge it, or close it. Use the repository context menu to create a pull request from the current branch.

Settings

Manage OAuth or token sign-in, test connection, and edit secrets and variables.

Configuration

Multiple Gitea instances

Open Settings → Gitea Instances in the extension sidebar and choose Add Gitea Instance. Each URL has its own securely stored token: select that instance, choose Set token or Sign In with OAuth, then use Test Connection. Repositories are automatically routed to the configured instance matching their git remote host.

Discovery Modes

Tips

• Expand runs only when you need jobs or artifacts for faster refresh.
• Right click on items for context actions like Open in Browser.
• Click the status bar entry to jump to the extension view.

Troubleshooting

• Connection fails: verify the base URL and token scopes, then run "Test Connection".
• Missing repos: check the discovery mode and ensure your git remotes match the Gitea host.
• Slow refresh: increase the idle interval or reduce max runs/jobs in settings.

Security

Tokens are stored via VS Code SecretStorage and are never written to settings files.

Testing (contributors)

• pnpm test — unit tests plus hermetic Gitea mock integration (GiteaApi over local HTTP); no real credentials.
• pnpm run test:integration — only the mock integration file.
• Mock token used in tests is the documented fake string MOCK_GITEA_TOKEN in src/test/mock-gitea/fixture.ts — never commit a real Gitea PAT; use env / CI secrets for live checks.
• pnpm run test:live — optional smoke against a real instance (GITEA_BASE_URL, optional GITEA_TOKEN, optional GITEA_TLS_INSECURE, REQUIRE_LIVE_GITEA for strict CI).
• pnpm run test:e2e — VS Code extension host tests against the mock (after pnpm run compile and pnpm run bundle). See src/test/e2e/README.md.
• pnpm run test:e2e:gitea — VS Code extension host tests against the local Gitea fixture; Docker is required.
• pnpm run check — canonical fast contributor gate; pnpm run verify additionally runs both extension-host suites.
• Pull requests run the fast gate, coverage thresholds, and both extension-host suites in CI.

Contributing

See CONTRIBUTING.md.

License

MIT. See LICENSE.