A VS Code editor that runs entirely in the browser for self-hosted Gitea, the
equivalent of pressing . on a GitHub repository. A Web IDE tab on every repository page, or the . key,
opens the repository at the current branch, tag, commit or pull request in a new browser tab. Edits stay in
the browser until you commit them, and the repository is never cloned.
Gitea serves the editor as plain static files: there is no extra server, reverse proxy or Node process at runtime. The editor is made of two parts:
- the workbench: the VS Code user interface itself (editor, file explorer, search, extensions view), the official VS Code web build published by Microsoft;
- this project's extension, which connects the workbench to Gitea: it reads files through Gitea's API, keeps your edits, and commits them.
VS Code runs extensions, including this one, in the extension host: a separate hidden frame and worker in the same browser tab.
Features:
- Local saves in browser storage; an explicit commit creates one Gitea commit.
- Branches, staging, protected-branch handling, pull request creation and remote change detection.
- Search over the repository and your pending changes, and TypeScript and JavaScript language features.
- Extensions from Open VSX (web extensions only), with an optional operator allowlist.
- A virtual shell (Gitea: Open Shell) over your pending changes, with no process execution.
- Native VS Code Settings Sync, stored in your own Gitea account.
- Sign in with Gitea OAuth (silent re-sign-in from your Gitea web session) or a personal access token.
- Gitea or Forgejo: the test suites run against Gitea 1.24.6; the local demo instance (
npm run instance:start) runs 28.2.0. The installer and the Web IDE tab were also run against Gitea 1.21.11, 1.22.6 and 1.23.8 and Forgejo 11 and 12 (a disposable server for each; no browser suite). Differences by version:- Gitea before 1.23 and Forgejo have no "skip authorization" option for OAuth applications. Users approve an authorization page at each sign-in, and the editor does not sign in on load: the first commit offers Sign In.
- Gitea before 1.24 does not tell templates the viewed ref; the tab takes it from the older variables. Forgejo
and Gitea 1.21 have no
ctx.Consts; the tab takes the code unit fromUnitTypeCode. - Settings Sync needs Gitea 1.24 or later.
- Browsers: Chromium, Firefox and WebKit (Safari's engine).
- HTTPS: serve Gitea over HTTPS. Plain
httpworks onlocalhost,127.0.0.1and[::1]. - To build from source: Node.js 22 or newer. The prebuilt release archive needs no Node.
- To install (
install.sh, no Node): a POSIX shell and the usual utilities,tar,gzipand one ofsha256sum,shasumoropenssl;--workbench=download(the default) also needscurlorwget. The installer's checks of a running Gitea usecurlwhen it is present.
Installing copies files into Gitea's custom directory and needs no change to Gitea itself.
GITEA_CUSTOM: Gitea's custom directory, where Gitea looks for extra templates and static files. Rungitea helpas the user that runs Gitea and look forCustomPathunder "DEFAULT CONFIGURATION" (the same output showsConfigFile, theapp.iniin use). In the official Docker image it is/data/gitea, in the rootless Docker image/var/lib/gitea/custom. The directory must exist.ROOT_URL: the public address of your Gitea, exactly as set byROOT_URLin the[server]section of Gitea'sapp.ini, for examplehttps://git.example.com/. If Gitea is served under a sub-path, the sub-path is part of it: withROOT_URL = https://git.example.com/git/, passhttps://git.example.com/git/. The editor builds every link and API call from this value, so it must match. The installer reads it fromapp.iniwhen you leave it out.- Workbench source: where browsers get the VS Code workbench (see step 2).
- OAuth application: a registration in Gitea that lets the editor sign users in through Gitea's own login page, so nobody pastes a token (see step 3).
- Personal access token (PAT): a password-like token a user creates in Gitea under Settings >
Applications > Manage Access Tokens. The editor accepts one when there is no OAuth application, or when a
user prefers it. For reading and committing, give it the
repositorypermission as Read and Write; Settings Sync also needsuseras Read and Write. - Gallery: the extension marketplace the Extensions view searches, by default Open VSX.
The release is a directory, gitea-dev/, with the installer (install.sh), the editor files, Gitea's template
for the Web IDE tab, workbench.json, which pins the exact workbench build by commit and SHA-256 checksum, and
LICENSE and THIRD_PARTY_NOTICES.txt.
Either download a prebuilt archive and check it:
sha256sum -c gitea-dev-VERSION.tar.gz.sha256
tar -xzf gitea-dev-VERSION.tar.gzor build it from source (writes dist/gitea-dev/; npm run package packs it as an archive):
npm ci --ignore-scripts
npm run buildThe installer installs the pinned VS Code workbench into GITEA_CUSTOM, and Gitea serves it. Use the default,
download, unless the install host has no internet access.
| Mode | Use it when | Needs |
|---|---|---|
download (default, recommended) |
The install host can reach vscode.download.prss.microsoft.com. |
curl or wget. |
local |
The install host has no internet access. | --workbench-archive=PATH: the archive named by url in the release's workbench.json, copied to the install host. |
Both modes install the same build, checked against the SHA-256 pinned in workbench.json.
Recommended. With it, users sign in through Gitea: they allow access once, and later loads sign in silently. Skip this step to have users sign in with personal access tokens.
Use the administrator UI (A), so the application belongs to the instance. B and C create it under one user account.
| Way | Owner | Result | |
|---|---|---|---|
| A | Administrator UI (recommended) | the instance | A Client ID to pass with --oauth-client-id. |
| B | install.sh --create-oauth-app |
the token's user | The installer creates or reuses the application and installs its Client ID. |
| C | Gitea API with curl |
the account you authenticate as | A Client ID to pass with --oauth-client-id. |
As an administrator, open Site Administration > Integrations > Applications
(<ROOT_URL>/-/admin/applications). Without administrator rights, any user can create the same application under
Settings > Applications (<ROOT_URL>/user/settings/applications); it then belongs to that user's account.
Under Create a new OAuth2 Application, fill in:
| Field | Value |
|---|---|
| Application Name | Any name users will recognize on the consent page, for example Gitea Web IDE. |
| Redirect URIs | <ROOT_URL>/assets/gitea-dev/oauth-callback.html, for example https://git.example.com/git/assets/gitea-dev/oauth-callback.html. |
| Confidential Client | Uncheck it (Gitea checks it by default). |
| Skip authorization for public clients after granting access once | Check it (Gitea enables it once Confidential Client is unchecked). |
Click Create Application and copy the Client ID; it is the value of --oauth-client-id. The client
secret Gitea shows is not used.
Give the installer a personal access token in the environment variable GITEA_TOKEN, with the user permission as
Read and Write, and add --create-oauth-app (not together with --oauth-client-id):
GITEA_TOKEN=TOKEN sh gitea-dev/install.sh /var/lib/gitea/custom --create-oauth-appGitea must be running at ROOT_URL. The installer reuses the token owner's application named Gitea Web IDE, or
creates one, and prints its Client ID. If the existing application has other settings, the installer says what to
fix and changes nothing.
With the credentials of the account that should own the application:
curl -u USER -H 'Content-Type: application/json' \
-d '{"name":"Gitea Web IDE","confidential_client":false,"skip_secondary_authorization":true,"redirect_uris":["https://git.example.com/git/assets/gitea-dev/oauth-callback.html"]}' \
https://git.example.com/git/api/v1/user/applications/oauth2-u USER makes curl ask for that user's password. Instead of a password you can pass a personal access token
with the user permission as Read and Write: -H "Authorization: token TOKEN". The response's client_id is the
value for --oauth-client-id.
sh gitea-dev/install.sh GITEA_CUSTOM [ROOT_URL] [OPTIONS] # prebuilt release
sh dist/gitea-dev/install.sh GITEA_CUSTOM [ROOT_URL] [OPTIONS] # release built from source (npm run build)Run it as the user that owns GITEA_CUSTOM. The installer first checks its arguments, the custom directory,
Gitea's app.ini (GITEA_CUSTOM/conf/app.ini, or --app-ini), the workbench archive and, when Gitea is
running, ROOT_URL and the OAuth application. If anything is wrong it prints each problem with the value
expected and changes nothing.
It then writes:
GITEA_CUSTOM/public/assets/gitea-dev/: the start page, the service worker,configuration.jsonwith your settings, and a versioned directory with the editor, its extension and the workbench. Gitea serves these at<ROOT_URL>/assets/gitea-dev/.GITEA_CUSTOM/templates/custom/extra_tabs.tmpl: the template that adds the Web IDE tab to repository pages, andpublic/assets/gitea-dev/shortcut.js, the.key handler. The installer never overwrites a different existing copy of either; merge your changes and rerun.
Examples:
# Workbench downloaded once and served by Gitea, OAuth sign-in
sh gitea-dev/install.sh /var/lib/gitea/custom https://git.example.com/ --oauth-client-id=CLIENT_ID
# Air-gapped: archive copied in, no gallery
sh gitea-dev/install.sh /var/lib/gitea/custom https://git.example.com/ --workbench=local \
--workbench-archive=/tmp/vscode-web.tar.gz --gallery=off --webviews=disabledRerunning with other options reconfigures the installation in place.
Gitea loads templates when it starts (in production mode), so restart it after the first install or when
extra_tabs.tmpl changed, and after editing app.ini. Static files need no restart.
To check: <ROOT_URL>/assets/gitea-dev/configuration.json shows your settings; a repository page shows the
Web IDE tab; clicking it opens the editor with the repository's files in the Explorer.
- Open: click Web IDE on a repository page, or press
.(not while typing in a field or dialog). The editor opens the current branch, tag or commit; on a pull request page it opens the head branch (the fork's, for a fork) or the head commit when the branch is gone. - Sign in (public repositories need none): Gitea: Sign In with OAuth, or Gitea: Sign In with
Personal Access Token. Committing needs
write:repository(a read-only token reads but its writes get 403, docs/testing.md); Settings Sync needsread:userandwrite:user. - Edit and save: saves stay in the browser, survive a reload, and appear in Source Control. Gitea: Discard Changes and Gitea: Discard All Changes drop them.
- Commit: in Source Control, stage files (or leave everything unstaged to commit all), type a message and press Ctrl+Enter or click Commit (enabled while changes are pending; its drop-down has Commit to New Branch). A note under the box names the branch that receives the commit, or says that a tag or commit is read-only. The ... menu groups the rest: Checkout to..., Fetch, and the Commit, Changes and Branch submenus. One commit lands on the opened branch. If the remote head or a file changed meanwhile, the editor reports the conflict and keeps your changes.
- Branches and pull requests: click the branch in the status bar to switch branch or tag (Gitea: Checkout to...), Gitea: Create Branch, and Gitea: Commit to New Branch; a protected branch that refuses a commit offers a new branch automatically. Gitea: Create Pull Request opens a pull request. While the window is focused the editor polls the branch head and offers Update when it moves.
- Search: Quick Open and Find in Files cover the repository and your pending changes. The first text search downloads the commit's archive from Gitea and keeps it in IndexedDB.
- Language features: TypeScript and JavaScript use the bundled browser language service. Other languages need web extensions.
- Shell: Terminal > New Terminal (or the Open Gitea Shell button in the empty Terminal panel, or Gitea: Open Shell) opens a terminal with a bash interpreter over
/workspace, the repository. Writes go to your pending changes; nothing is committed and no process or network is available (curl,python,nodeandgitare absent). The overlay cannot store links, file modes or modification times. - Files: Git LFS files open read-only with their real content; symlinks inside the repository follow to their target; submodules are listed but cannot be opened.
- Theme: the editor follows your Gitea theme as light or dark.
- Settings Sync: turns on by itself after sign-in and stores your settings, keybindings, snippets, tasks and
extension list in your Gitea user Actions variables (
WEBIDE_SYNC_*). Turn it off in the native Settings Sync UI and it stays off. - Extensions: use the Extensions view to search Open VSX and install web extensions. Installations persist in
the browser profile; updates are manual. Only web extensions run: the extension host is a web worker that
loads an extension's
browserentry, so an extension with onlymain, Node-based extensions, desktop executables and arbitrary.vsixuploads do not work. The host also rejects ES-module entries (.mjs, or"type": "module"without a.cjsentry). Themes, snippets and browser formatters and language services work. Extensions can connect to Gitea, the gallery and--connect-srchosts.
Behavior details and limits are in plan.md; sync details are in docs/settings-sync.md.
install.sh takes these arguments. Options are
written --name=value or --name value. To change a setting, rerun the installer with all the options you
want; do not edit the installed files.
| Argument | Default | What it does | When to use it |
|---|---|---|---|
GITEA_CUSTOM (first) |
required | Gitea's custom directory, where the files are installed. It must exist, be writable, and be empty or hold Gitea's conf, public, templates or options. |
Always. Find it with gitea help (CustomPath). |
ROOT_URL (second) |
[server] ROOT_URL of the app.ini |
Gitea's public address, equal to [server] ROOT_URL in app.ini: https://host[:port][/sub/path], or http on localhost, 127.0.0.1 or [::1]; lowercase host, plain path. |
Leave it out when the app.ini is found (see --app-ini); the installer reads it and says which value it used. Pass it when app.ini has no literal ROOT_URL. |
--workbench=download|local |
download |
Where the installer gets the workbench (step 2). | local when the install host cannot reach the internet. |
--workbench-archive=PATH |
none | The workbench archive file; it must match the SHA-256 pinned in workbench.json. Required by --workbench=local, refused otherwise. |
Air-gapped installs. |
--oauth-client-id=ID |
none | Enables Sign In with OAuth with this OAuth application (step 3): 1-128 letters, digits or hyphens. | When you registered the application in the administrator UI (recommended). Without an OAuth application users sign in with a personal access token. |
--create-oauth-app |
off | Finds or creates the public OAuth application Gitea Web IDE with the personal access token in the environment variable GITEA_TOKEN, and installs its Client ID. The application belongs to the token's user, not the instance. Refused with --oauth-client-id. |
Only when the administrator UI is not an option (step 3, B). |
--gallery=URL|off |
https://open-vsx.org |
The extension gallery the Extensions view uses, which browsers contact directly. off disables installing extensions. |
off on air-gapped sites or to forbid extensions; a URL for a private Open VSX instance. |
--extensions-allowlist="publisher.name ..." |
all | Only these gallery extensions are listed and downloadable. Ids are lowercased, separated by spaces, tabs, newlines or commas; an empty list is refused. | To limit extensions. Enforced by the browser, so not a security boundary (Security model). |
--connect-src="SOURCE ..." |
none | Extra hosts extensions may connect to: https://host[:port][/path], wss://, or loopback http:///ws://; a leading *. needs two more labels. |
When an extension needs a service. |
--webviews=vscode-cdn|disabled |
vscode-cdn |
Webviews are the panels extensions draw with HTML (Markdown preview, extension pages). vscode-cdn hosts them on Microsoft's https://*.vscode-cdn.net; disabled turns them off. |
The default. disabled when browsers cannot reach *.vscode-cdn.net, or must not contact Microsoft. |
--app-ini=PATH |
GITEA_CUSTOM/conf/app.ini if present |
The app.ini Gitea runs with, for the installer's check of ROOT_URL; the installer never changes it. |
When Gitea's configuration is elsewhere (ConfigFile in gitea help, for example /etc/gitea/app.ini). |
Webviews in detail: they always run on their own *.vscode-cdn.net origin, with no access to the Gitea page,
its cookies or the editor's stored secrets (tests/browser/webviews.spec.ts). The built-in Markdown preview
opens but stays empty, because its styles and scripts come from Gitea, whose static files lack the
Cross-Origin-Resource-Policy header the webview page requires; webviews with inline content work.
The installer writes GITEA_CUSTOM/public/assets/gitea-dev/configuration.json, which the start page reads. The
same values are also built into the start pages and the service worker, so rerun the installer instead of
editing it.
| Field | Meaning |
|---|---|
instance |
ROOT_URL without the trailing slash; editor links must point to this origin and sub-path |
version |
Directory holding this release's editor, extension and workbench |
oauthClientId |
--oauth-client-id, or null |
gallery |
Gallery address, or null when disabled |
extensionsAllowlist |
Lowercase publisher.name ids, or null for all |
connectSrc |
--connect-src, space-separated |
webviews |
vscode-cdn or disabled |
testMode |
false; the browser test harness sets it |
Set in the editor's Settings UI or settings.json (packages/gitea-vscode-web/package.json):
| Setting | Default | Meaning |
|---|---|---|
giteaWebIde.autoFetch.enabled |
true |
Poll the remote branch head while the window is focused; updating always asks |
giteaWebIde.autoFetch.interval |
60 |
Seconds between checks (minimum 15) |
gitea.archive.prefetch |
onSearch |
When to download the commit archive: onSearch, onOpen or off |
gitea.archive.maxRepositoryMiB |
128 |
Largest total file size for which the archive is fetched |
gitea.archive.maxFiles |
50000 |
Largest file count for which the archive is fetched |
gitea.archive.maxFileMiB |
25 |
Larger files are left out of the archive cache and read individually |
gitea.archive.maxDownloadMiB |
128 |
Largest compressed download |
gitea.archive.idleTimeoutSeconds |
30 |
Abort when no data arrives for this long |
gitea.archive.startTimeoutSeconds |
120 |
How long to wait for Gitea to build the archive |
gitea.archive.cacheMiB |
512 |
Total size of stored archives; least recently used removed first |
Extensions are trusted code, as in desktop VS Code: install only extensions you trust. Opening a repository cannot install an extension (workspace recommendations are disabled). What an extension can reach:
- Where extensions run: on the Gitea origin, in a frame served by Gitea.
- Gitea web session: usable. An extension can load Gitea pages with the user's session cookie, CSRF token included, so an extension in an administrator's editor can use site administration.
- Stored personal access token: an extension can decrypt it from the editor's browser storage.
- Network access: only Gitea, the gallery and
--connect-srchosts (CSP). - Microsoft at runtime: contacted for webviews, unless
--webviews=disabled.
All extensions share one extension host with the editor's own extension, which holds the user's
Gitea token, and any extension can ask it for a Gitea session (the gitea authentication provider, used by
Settings Sync).
- The allowlist is advisory. The editor hides other extensions and refuses their downloads, and the workbench disables installed extensions that left the list, but the browser enforces this, so a user can bypass it. It is not a security boundary.
- Tokens are never put in links or settings. OAuth tokens stay in memory, so signing out of Gitea ends editor
access on the next load. A personal access token is kept in the browser's IndexedDB (
gitea-web-ide-secrets), encrypted with AES-GCM under a key the page cannot export, so sign-in survives a reload. Script on the editor origin can still use that key, so this protects data at rest, not against extensions on that origin. Gitea: Sign Out clears local credentials and disables silent sign-in until the next interactive sign-in; revoke an OAuth grant in Gitea user settings. - What Gitea sees: API calls with the user's token, commit archive downloads, a page request to read the
user's theme, and Settings Sync data in
WEBIDE_SYNC_*user Actions variables (gzip, not encrypted; visible in the user's settings when Actions is enabled). Telemetry is off. Pending edits reach Gitea only through a commit. - Isolation: the editor page is cross-origin isolated, with a restrictive Content Security Policy set by the
editor's service worker. Only the extension host frame allows
'unsafe-eval', which the workbench's extension loader needs.
Design and requirements: plan.md. A session bridge (sign-in from the Gitea session, no token in the browser) would need a Gitea backend patch and is not built: docs/session-bridge.md.
Upgrade the editor: rebuild (or take a new archive) and rerun the installer with the same options. Each
release has its own <12 hex>-<12 hex> directory under $GITEA_CUSTOM/public/assets/gitea-dev/; earlier version
directories stay for open sessions and can be deleted later. Restart Gitea only if the template changed.
Upgrade the workbench: review a new official VS Code web release, then replace version, commit, url
and sha256 in config/workbench.json together, build and install again (with --workbench=local, pass the new
archive). To roll a deployment back, restore the previous pin, rebuild and reinstall.
Uninstall: delete $GITEA_CUSTOM/public/assets/gitea-dev/ (it holds shortcut.js too) and
$GITEA_CUSTOM/templates/custom/extra_tabs.tmpl (only the Web IDE part, if you merged it into another
template), then restart Gitea. Delete the OAuth application in Gitea; users can delete the WEBIDE_SYNC_*
variables in their Gitea settings and clear the site data in their browsers.
npm run build 2>&1 | tee -a ./build.log
npm run typecheck 2>&1 | tee -a ./build.log
npm test 2>&1 | tee -a ./build.log
npm run test:integration 2>&1 | tee -a ./build.log
npx playwright install chromium firefox webkit
npm run test:browser 2>&1 | tee -a ./build.logReleases. .github/workflows/ci.yml runs typecheck, the unit tests, the build and the packaging on every push to
main and every pull request, and uploads the archive as a workflow artifact. A release is a tag named
v<version>, where <version> is version in package.json:
npm version --no-git-tag-version 0.3.0 # edit package.json and package-lock.json
git commit -am "Release 0.3.0"
git push origin main
git tag v0.3.0
git push origin v0.3.0The same workflow runs on the tag. It fails when the tag and package.json disagree, then builds and packs as above
and a second job creates a GitHub release with gitea-dev-v<version>.tar.gz, its .sha256 file and generated
notes. Running the CI workflow by hand from the Actions tab with an existing tag as input publishes that tag's
release the same way. A tag with a hyphen (v0.3.0-rc.1) is published as a pre-release. The integration and browser
suites are not run in Actions.
Suites, prerequisites, the disposable Gitea fixtures and what is not covered: docs/testing.md.
Workbench assets. config/workbench.json pins the official standalone web archive
(vscode-web.tar.gz, release 1.143.1) by version, commit, URL and SHA-256; latest is never resolved. The
archive, not VS Code Server (which contains a remote agent), is used. The build only copies the pin into the
release; the installer fetches and verifies the workbench. For development and tests, the asset provider caches the
pinned archive in data/vscode-web/: it requires the browser workbench bundle, the extension-host worker and
its iframe page, rejects server layouts, remote-agent files and native executables
(packages/asset-provider/src/validate.ts), and checksum-verifies every archive before extraction. The browser
test harness installs with --workbench=local from data/vscode-web/downloads/<sha256>.tar.gz when it
exists, else with --workbench=download (scripts/cached-workbench.mjs).
npm run assets -- warm # download and install the pin
npm run assets -- status
npm run assets -- validate
npm run assets -- bundle /path/to/offline-workbench # destination must not exist
npm run assets -- rollback FULL_INSTALLED_COMMIT
npm run assets -- pruneDesign notes on the cache and locks are in plan.md.
Local Gitea instance. The local installation runs Gitea 28.2.0 with SQLite at http://localhost:3000, serving
the editor itself with the workbench from the local download cache (npm run assets -- warm), or downloaded
when the cache is empty, with the OAuth application registered automatically and the demo repositories
web-ide-demo (public) and private-demo, owned by the administrator:
npm run instance:start
npm run instance:status
npm run instance:stopThe administrator credentials are in data/local-gitea/credentials.json. Database, repositories, configuration and
logs persist under data/local-gitea/. The services bind to loopback only. Run instance:start again after a
machine or WSL restart. The Gitea binary URL and checksum are pinned in config/gitea-instance.json; build the
project before the first start, because instance:start installs the current build.
Repository layout: packages/ (asset-provider, editor-host, gitea-repository, gitea-vscode-web),
gitea/custom/ (Gitea template and shortcut script), scripts/, tests/, docs/.
The Gitea client library is described in packages/gitea-repository/README.md.
MIT. The release archive contains no Microsoft code. The npm packages bundled into it, among them
just-bash (Apache-2.0) and the packages its browser bundle inlines, are credited with their license texts in the
release's THIRD_PARTY_NOTICES.txt; THIRD_PARTY_NOTICES.md covers the Microsoft typings
in this repository. The VS Code web workbench is Microsoft's, under the terms in
the LICENSE file of its archive; the installer installs it into $GITEA_CUSTOM.