go-gitea/gitea

[Feature] Custom endpoints

Closed this issue · 1 comments

d1nch8g commented

Feature Description

Summary

I propose adding a feature that allows administrators to mount custom external services onto Gitea's web server under a defined URL path prefix (e.g., {base_url}/my-tool/). This would seamlessly integrate custom tools into Gitea.

Motivation

Many organizations and users have complementary tools they wish to integrate closely with their Gitea instance (e.g., a custom CI system, a documentation portal, a specialized dashboard). Currently, this requires:

  1. Serving the tool from a separate host/port, breaking single-sign-on and the unified experience.
  2. Complex and error-prone external reverse proxy configuration.

This feature would provide a first-class, secure way to achieve this integration within Gitea itself, laying the groundwork for a future plugin ecosystem.

Proposed Solution (Phase 1)

Core Concept

A new configuration section in app.ini will allow an admin to define a list of "mount points."

Configuration

; ... existing app.ini sections ...

[endpoint]
ENABLED = true

[[endpoint.proxies]]
url_prefix = /my-ci-service
backend_url = http://localhost:3000
; Optional: Control pass-through of authentication
send_auth_header = true
; Optional: Restrict access based on Gitea's permission system
required_permission = admin ; none, read, write, admin

[[endpoint.proxies]]
url_prefix = /custom-wiki
backend_url = http://wiki.internal.company.com/
send_auth_header = false
required_permission = read

Functionality

  1. Routing: Any request to https://gitea.example.com/{my-ci-service}/** is transparently proxied to http://localhost:3000/**.
  2. Authentication & Authorization:
    • If send_auth_header = true, Gitea would validate the user's session cookie first (just like any other protected route).
    • It would then add standard auth headers (e.g., Authorization: Bearer <jwt>, X-Gitea-User: <username>, X-Gitea-Roles: <roles>) to the outgoing request to the backend service.
    • The required_permission check would ensure the user has the required access level (e.g., admin) before the request is ever proxied.
  3. Security: The feature is disabled by default. No endpoints are active without explicit admin configuration.

Why start with static config?

This Phase 1 approach is:

  • Minimal: It adds the core functionality without a large UI codebase.
  • Secure: It's controlled via the existing config file management.
  • Powerful: It immediately solves the integration problem for many use cases.
  • A Foundation: It creates the backend architecture that a future UI (Phase 2) and plugin system (Phase 3) can build upon.

Unresolved Questions / For Discussion

  1. Should it be possible to start tools with exec.Cmd as a background?
  2. How to pass frontend settings, to reuse gitea styling on frontend routes?
  3. Would it be possible to reuse/extend templates with additional pages?

Screenshots

No response

wxiaoguang commented

I believe you need a reverse proxy for this case.

  • 👍2