Gitea — API Surface#

API types#

Gitea exposes five distinct API surfaces to different classes of callers:

1. REST API (/api/v1) — public Swagger-documented REST API for all external integrations
2. Package Manager APIs (/api/packages, /v2) — 20+ protocol-native package registry endpoints
3. Actions Runner API (/api/actions) — Connect-RPC (protobuf-over-HTTP) for CI runner communication
4. Private/Internal API (/api/internal) — HTTP IPC between the git hook subprocess and the web server
5. Web UI (/) — Full HTML rendering surface (same chi router, not analyzed in depth here)

REST/HTTP API (/api/v1)#

Router#

• Framework: github.com/go-chi/chi/v5 via a custom modules/web.Router wrapper
• Route registration: All routes are registered explicitly in routers/api/v1/api.go:Routes(), a ~900-line function
• Documentation: Swaggo-style godoc // swagger:operation comments on handler functions; spec served at /api/swagger (when enabled)

Middleware chain#

Applied in order via m.BeforeRouting / m.AfterRouting:

1. securityHeaders() — sets X-Frame-Options, X-Content-Type-Options, X-XSS-Protection, etc.
2. CORS handler (github.com/go-chi/cors) — optional, configurable allowed origins/methods
3. context.APIContexter() — creates APIContext (extends Base with APIOrganization, APIRepo, etc.), sets up request data store
4. checkDeprecatedAuthMethods — warns via header when legacy ?token= or ?access_token= query params are used
5. apiAuth(buildAuthGroup()) — resolves the caller identity; auth methods tried in order: OAuth2 → HTTPSign → Basic (→ ReverseProxy if enabled)
6. verifyAuthWithOptions — enforces RequireSignInViewStrict if configured
7. Per-route: tokenRequiresScopes(...) — enforces fine-grained scope on the API token (read/write per category)
8. Per-route: repoAssignment() / orgAssignment() — loads the repo/org from path params, checks visibility

Authentication#

Six supported methods (evaluated by the auth.Group pipeline):

• OAuth2 Bearer token — Authorization: token <TOKEN> header (preferred)
• HTTPSign — HTTP Signatures with SSH key (for SSH-based clients)
• Basic auth — deprecated for removal in v1.23; still accepted
• Reverse proxy — optional, reads user from X-Forwarded-User or configured header
• Session cookie — inherited from web context (for same-origin browser requests)
• Sudo — site admins can impersonate users via ?sudo=<username> or Sudo: header

Token scopes (introduced in Gitea 1.19): tokenRequiresScopes enforces minimum scope per route group. Categories: repository, issue, notification, user, organization, package, admin, activitypub. Each category has read/write granularity, and tokens can be restricted to public resources only.

Key endpoint groups#

Notable endpoints:

• GET /api/v1/repos/{owner}/{repo}/contents/{filepath} — file contents
• POST /api/v1/repos/{owner}/{repo}/contents/{filepath} — create file (creates a commit)
• PUT /api/v1/repos/{owner}/{repo}/pulls/{index}/merge — merge PR with configurable strategy
• POST /api/v1/repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches — trigger workflow
• GET /api/v1/repos/{owner}/{repo}/git/trees/{sha} — git object tree
• GET /api/v1/repos/{owner}/{repo}/compare/* — diff between refs

Package Manager APIs (/api/packages, /v2)#

Gitea doubles as a full-featured package registry. Each package type speaks its native protocol; these routes are separate from the REST /api/v1 routes and are mounted at /api/packages/{username}/{type}/....

Router#

• Same chi wrapper as the REST API
• Separate CommonRoutes() and ContainerRoutes() entry points in routers/api/packages/api.go
• Authentication: OAuth2, Basic, plus format-specific auth helpers (nuget.Auth, chef.Auth, packages/auth.go)
• Container routes live at /v2/ (OCI Distribution Spec root)

Supported package formats (20+)#

Each format has its own sub-package under routers/api/packages/<format>/, typically with a *.go file implementing the format-specific handlers.

Container (OCI) routes#

• Mounted at /v2/ (not /api/packages)
• Full OCI Distribution Spec 1.0: push (PUT blob, POST upload, PUT manifest), pull (GET manifest, GET blob), delete, referrers, catalog, list tags
• ContainerRoutes() returns a *web.Router with OCI-specific error format (JSON errors array)
• Auth: WWW-Authenticate: Bearer challenge flow (token service built into Gitea)

Actions Runner API (/api/actions)#

Gitea Actions uses a Connect-RPC (protobuf over HTTP/1.1) protocol to communicate with self-hosted runners.

• Proto definition: routers/api/actions/artifact.proto; generated code in artifact.pb.go
• Services registered:
  • PingService — health check for runner ↔ server connectivity
  • RunnerService — job lifecycle: register, fetch job, update job status, submit logs
• Framework: connectrpc.com/connect (formerly bufbuild/connect-go)
• Route pattern: All POSTs to /api/actions/{service}/{method} via m.Post(path+"*", handler.ServeHTTP) — Connect uses HTTP/1.1 POST with Content-Type: application/connect+proto
• Artifact handling: Additional handlers in artifacts.go / artifactsv4.go for uploading/downloading CI artifacts (GitHub Actions-compatible artifact API v3 + v4)

Private/Internal API (/api/internal)#

This surface is not public — it is used exclusively by Gitea’s own subprocess invocations (gitea serv, gitea hook). It runs on the same HTTP listener but is protected by a shared InternalToken checked via X-Gitea-Internal-Auth: Bearer <token>.

Authentication#

authInternal middleware does a subtle.ConstantTimeCompare of the Bearer token against setting.InternalToken. No public access is possible without this secret.

Route table (routers/private/internal.go)#

CLI (gitea binary)#

Framework#

github.com/urfave/cli/v3 (not Cobra). The main app is constructed in cmd/main.go:NewMainApp().

Global flags#

• -w / --work-path — sets AppWorkPath
• -c / --config — path to app.ini (default: {WorkPath}/custom/conf/app.ini)
• -C / --custom-path — sets CustomPath

All three flags are inherited by subcommands via a Before hook that calls prepareWorkPathAndCustomConf.

Command structure#

Subcommands requiring config (inherit global flags, call InitWebInstalled or subset):

admin sub-tree:

Standalone subcommands (no config required):

Flag patterns#

• Global flags propagate via Before hook to all subcommands in subCmdWithConfig
• urfave/cli v3 uses typed flag structs (&cli.StringFlag{Name: ..., Aliases: ..., TakesFile: ...})
• Environment variable binding: CLI does not bind env vars directly; modules/setting reads GITEA_CUSTOM, GITEA__SECTION__KEY patterns separately

Notable API design decisions#

1. Five isolated API surfaces, one binary. The same gitea binary simultaneously serves the web UI, the public REST API, 20+ native package protocols, the Connect-RPC Actions protocol, and the internal git-hook IPC. Each surface is chi-mounted at a distinct prefix and has its own middleware stack and context type.

2. Scope-based token authorization. The REST API uses a two-dimensional permission model: {category}:{read|write} (e.g., repository:write, issue:read). This is enforced by tokenRequiresScopes(...) middleware — HTTP method determines read vs. write, route group determines category. Public-only tokens are also supported (scope.PublicOnly()), preventing access to private repos with a single token scope restriction.

3. Private IPC via HTTP, not pipes. The git hook subprocess communicates with the running web server over an HTTP Unix socket rather than stdout/environment variables. This enables typed, version-safe data exchange and lets the server enforce branch protection rules synchronously during the git push, before git accepts the pack.

4. Package manager protocol fidelity. Each package registry sub-router replicates the exact protocol of the target ecosystem (e.g., OCI spec for containers, Cargo sparse index for Rust, PyPI Simple API for Python). This means package managers like pip, cargo, npm, helm, and docker can be pointed at Gitea without any client modification.

5. Connect-RPC (not REST) for the runner protocol. The Gitea Actions runner uses connectrpc.com/connect (protobuf-over-HTTP) rather than a REST API. This means strong schema evolution guarantees and efficient binary encoding for the tight runner ↔ server loop.

6. Swagger generated from godoc comments. Route handler functions carry // swagger:operation godoc annotations. The swagger spec is generated at build time with swaggo and served as a static file. No runtime code generation. This keeps the spec in sync with the code via CI.