Gitea

Proxy for a self-hosted Gitea instance's REST API through the managed gateway. Repos, file contents, issues, and pull requests — all operations are gated by PBAC policy.

Authentication

Gitea authenticates REST calls with an access token. This connector supports three auth modes, chosen per managed resource at install time via the Authentication field:

• OAuth passthrough (idp_passthrough, default, recommended) — each user grants access once through this Gitea instance's own OAuth2 consent screen (requires a gitea IdentityProvider registered on this instance — POST /admin/api/identity-providers, preset in idp-presets/gitea.json; Gitea has shipped a full OAuth2 provider, including OIDC discovery at /.well-known/openid-configuration, since 1.8.0). No token to copy or paste, and it refreshes itself automatically.
• Per-user access token (user_secret) — each user links their own Gitea access token once, through a PolicyArc-hosted browser page reached by MCP URL elicitation on the first call. The token posts only to the AS (never through the MCP client or the model), is stored encrypted per (subject, resource), and is sent as Authorization: token <token> on that user's calls — so Gitea attributes every action to the real user, with that user's own repository permissions. Use this when a gitea IdP isn't registered on this instance, or a customer prefers minting a token directly over an OAuth consent screen.
• Shared token (static) — every call uses one operator-held token from the token_env secret, sent verbatim as the Authorization header value (include the token prefix). Gitea attributes all calls to that one identity.

Either way, PolicyArc enforces per-user authorization at the gateway via policy before the request reaches Gitea. See Per-user upstream credentials for how the user_secret collection flow works.

Setup

• base_url — your Gitea instance's base URL, e.g. https://gitea.example.com.
• upstream_auth.type — idp_passthrough (default), user_secret, or static.
• token_env — static mode only — a secret holding the shared access token, including its token prefix. Hidden unless static is selected.

Registering the Gitea IdP (for idp_passthrough)

On the target Gitea instance: Site Administration → Applications (or a user's own Settings → Applications for a personal app) → create a new OAuth2 application, set its Redirect URI to the AS's /oauth2/callback URL, and grant read:repository/write:repository/read:issue/write:issue. Register it once via POST /admin/api/identity-providers with idpId: "gitea" and issuer set to this instance's base URL. The server discovers the rest from {issuer}/.well-known/openid-configuration.

Creating a Gitea access token

Gitea → Settings → Applications → Generate New Token. Gitea's tokens are scope-checked per endpoint, not all-or-nothing — verified against a live Gitea 1.27 instance, this connector's full route set (including the read:user probe) needs read:user, write:repository, and write:issue. Grant less if you only need a subset (e.g. read:user + write:repository for file access without issues/PRs). In user_secret mode each user does this for themselves on the collection page; in static mode the operator provisions the shared token once.

Manifest reference

• ID: identos.gitea
• Version: 1.0.0
• Resource type: urn:connector:identos:gitea
• Capabilities: mcp

Supported auth modes

Type	Details
idp_passthrough	requires IdP gitea
user_secret	—
static	scheme header; header Authorization; setup fields: token_env

Setup fields

ID	Label	Default	Secret?	Notes
base_url	Gitea base URL	—	no	placeholder: https://gitea.example.com
upstream_auth.type	Authentication	idp_passthrough	no	idp_passthrough (recommended) has each user grant access through this Gitea instance's own OAuth2 consent screen — no token to copy or paste, and it refreshes itself. user_secret has each user paste their own access token instead. static uses one shared token for everyone.
token_env	Access token	—	yes	Used only for the static method. A secret holding a Gitea access token, sent verbatim as the Authorization header value — include the 'token ' prefix, e.g. 'token abc123...'. / shown when upstream_auth.type == 'static'

Scopes

Scope
gitea:repo:read
gitea:repo:write
gitea:issues:read
gitea:issues:write
gitea:pulls:read
gitea:pulls:write

Routes

Method	Pattern	Scope	Resource template
GET	/api/v1/repos/{owner}/{repo}	gitea:repo:read	gitea://{{owner}}/{{repo}}
GET	/api/v1/repos/{owner}/{repo}/contents/{filepath:.*}	gitea:repo:read	gitea://{{owner}}/{{repo}}
PUT	/api/v1/repos/{owner}/{repo}/contents/{filepath:.*}	gitea:repo:write	gitea://{{owner}}/{{repo}}
GET	/api/v1/repos/{owner}/{repo}/issues	gitea:issues:read	gitea://{{owner}}/{{repo}}
POST	/api/v1/repos/{owner}/{repo}/issues	gitea:issues:write	gitea://{{owner}}/{{repo}}
PATCH	/api/v1/repos/{owner}/{repo}/issues/{index}	gitea:issues:write	gitea://{{owner}}/{{repo}}/issues/{{index}}
GET	/api/v1/repos/{owner}/{repo}/pulls	gitea:pulls:read	gitea://{{owner}}/{{repo}}
POST	/api/v1/repos/{owner}/{repo}/pulls	gitea:pulls:write	gitea://{{owner}}/{{repo}}

MCP tools

Name	Scope	Description
get_repo	gitea:repo:read	Get metadata for a Gitea repository.
get_repo_file	gitea:repo:read	Read a file or directory listing from a Gitea repository at a given path. Returns base64-encoded content plus the blob sha needed to update it.
update_repo_file	gitea:repo:write	Update an existing file in a Gitea repository. Requires the current blob sha (from get_repo_file) to avoid clobbering a concurrent change.
list_issues	gitea:issues:read	List issues in a Gitea repository.
create_issue	gitea:issues:write	Open a new issue in a Gitea repository.
update_issue	gitea:issues:write	Update fields on an existing Gitea issue.
list_pull_requests	gitea:pulls:read	List pull requests for a Gitea repository.
create_pull_request	gitea:pulls:write	Open a pull request in a Gitea repository.