feat: add remote development environments

[ExplodingDragon]

This adds first-class Codespaces support to Gitea. Users can create Dev Container-based development environments from repository branches, commits, and pull requests; review the selected runtime environment, repository permissions, and injected secrets before creation; and manage lifecycle actions, logs, endpoints, resource usage, and auto-stop settings from Gitea.

Gitea acts as the authorization and lifecycle control plane, while separately deployed Codespace Managers provision and operate the development environments. Managers claim leased operations through authenticated RPC, and runtime access uses scoped credentials and short-lived open tokens. This keeps workload infrastructure outside Gitea web nodes while preserving Gitea's repository permissions and user ownership boundaries.

The change also adds site and personal Manager registration, environment-tag selection, administrator governance and reconciliation, scoped repository tokens, Codespace secrets, SSH authentication, and configuration for production deployments.

The accompanying Manager implementation is available at gitea/gitea-codespace, and the shared protocol module is maintained at gitea/codespace-proto-go.

I'm still working on the design and evaluating the implementation. You can find the current details here (zh-CN).

Developer verification

Use a Linux host with Incus initialized and a working storage pool and managed network. Run Gitea with Codespaces enabled and configure its public URL so it is reachable from the Incus instances; localhost clone URLs will point back to the instance and cannot reach Gitea.

Build the accompanying Manager, copy its example YAML, and set the Gateway public addresses, Incus endpoint, storage pool, network, and one environment tag for the local deployment:

git clone https://gitea.com/gitea/gitea-codespace.git
cd gitea-codespace
cp examples/config.example.yaml codespace.yaml
go build -o gitea-codespace .

Create a site registration token from Site Administration > Codespace Managers, or a personal token from User Settings > Codespaces > Managers. Register and start the Manager; the registration command prompts for the Gitea URL and token:

./gitea-codespace register --config codespace.yaml
./gitea-codespace serve --config codespace.yaml

Open a repository's Code > Codespaces tab and create an environment from either a repository devcontainer.json or the platform default. A successful end-to-end check reaches the Running state, streams grouped operation logs, opens the browser IDE, accepts the displayed SSH command, exposes a declared port, and completes stop, resume, and delete actions.

Screenshots

Codespace overview and runtime access

Web IDE

---

AI Disclosure:

This PR was designed and implemented using ChatGPT 6 astra high. All generated code has been manually reviewed by a human.

---

Close #27766
Close #33904

[GiteaBot]

@ExplodingDragon I noticed you've updated the locales for non-English languages. These will be overwritten during the sync from our translation tool Crowdin. If you'd like to contribute your translations, please visit https://crowdin.com/project/gitea. Please revert the changes done on these files. 🍵

[GiteaBot]

@ExplodingDragon I noticed you've updated the locales for non-English languages. These will be overwritten during the sync from our translation tool Crowdin. If you'd like to contribute your translations, please visit https://crowdin.com/project/gitea. Please revert the changes done on these files. 🍵

[a1012112796]

I think implement this huge feature as an individue oauth2 app/server is a better option.

[ExplodingDragon]

I think implement this huge feature as an individue oauth2 app/server is a better option.

@a1012112796 I think going with a separate OAuth2 app/server would actually lower integration with Gitea’s core and add unnecessary complexity and maintenance cost.

My goal for adding codespace support was to natively work with devcontainers for remote development—so we can quickly test/review PRs and also use it as a controlled AI agent environment for automation.

An external OAuth2 solution would require maintaining a separate user base and syncing identities, leading to issues with authorization, session management, token refresh, and, more importantly, it would be hard to restrict each request’s Gitea API scope (e.g., to specific repos or read‑only).

Doing it internally reuses Gitea’s existing permission models (users, orgs, repos) for fine‑grained control, reduces dependencies, and shrinks the attack surface.

In short, internal implementation fits Gitea’s architecture better and would be more stable and efficient for our scenarios, so I’d still advocate for making it a built‑in feature.

[lunny]

For performance reasons, it is better to use an int64 ID as the primary key.

[ExplodingDragon]

For performance reasons, it is better to use an int64 ID as the primary key.

This is intentional. We use a UUID to prevent enumeration, and the same ID will also be used on the manager /gateway side.

[ExplodingDragon]

TODO: Sorry, I’m not very familiar with Gitea’s frontend, so the UI part may need to be refactored to conform to the project’s standards.

[Sirherobrine23]

Hi, great work 👏, can you integrate URL handlers for Zed and VS Code?

• vscode://vscode-remote/ssh-remote+[<user>@]<host>[:<port>][/<path>]
• zed://ssh/[<user>@]<host>[:<port>][/<path>]

[lunny]

Gitea should connect to the workspace server, rather than the other way around, so that multiple Gitea instances can share the same workspace server.

[ExplodingDragon]

Gitea should connect to the workspace server, rather than the other way around, so that multiple Gitea instances can share the same workspace server.

@lunny Only a simple modification to the workspace server is needed to support this—allowing multiple Gitea instances to be registered simultaneously.