# Gitea App Spec

> Canonical path: `specs/app/gitea.md`
> Status: living-spec
> Scope: Gitea-specific App configuration, connection, webhook verification, Extension capability exposure, and pull request event delivery.
>
> Related specs:
> - [`specs/app/app-system.md`](./app-system.md)
> - [`specs/app/provider-watch-agent-mcp.md`](./provider-watch-agent-mcp.md)
> - [`specs/service/service-actor-platform.md`](../service/service-actor-platform.md)
> - [`specs/service/service-event-delivery.md`](../service/service-event-delivery.md)

## 1. Purpose

The Gitea App connects a workspace to one or more Gitea organizations or
repositories and exposes pull request collaboration capabilities through the App
UI and the authorized Gitea Extension.

## 2. Service actor model

Gitea is an App service actor:

```text
service_definition(kind=app, slug=gitea)
service_installation
service_connection
service_member
service_capabilities
service_target_bindings
```

Visible Gitea updates are authored by the Gitea service member. The message
source records whether the update came from direct App action, callback, or a
provider event delivery.

## 3. Configuration and connection

Workspace administrators configure the Gitea instance, credentials, webhook
endpoint, and repository or organization access. Runtime code resolves these
facts through the service actor connection and grant model. Gitea-specific
signature verification and payload normalization belong at the Gitea webhook
boundary.

## 4. Pull request subscriptions

Gitea pull request subscriptions are service event subscriptions:

```text
service_event_subscription(provider=gitea, event_family=pull_request)
service_webhook_receipt
service_event_delivery
```

Supported event filters include comments, reviews, status, synchronize, merge,
close, reopen, and explicitly enabled base branch push reminders where supported
by the provider payloads.

Lifecycle actions remain:

```text
create or reuse a subscription
list subscriptions
pause a subscription
resume a subscription
remove a subscription
```

The stable MCP tool names are compatibility/product action names and are mapped
to service event subscription operations.

## 5. Webhook flow

```text
POST /api/apps/gitea/webhook
  -> resolve Gitea service definition, installation, and connection
  -> verify signature
  -> normalize provider payload
  -> reserve service_webhook_receipt
  -> match service_event_subscriptions
  -> reserve service_event_deliveries
  -> write service-authored message or task discussion
```

Duplicate provider deliveries must not produce duplicate messages. Blocked or
invalid connections mark the relevant service event delivery state and diagnostics
without routing through schedules or automation runs.

## 6. Gitea-specific payload rules

Gitea does not use the GitHub App manifest flow. Workspace admins configure the
instance URL, display name, API token, and webhook secret directly, then connect
an organization or repository target. Gitea callback routing must use the
configured connection and provider resource path; payload owner/repository fields
are not trusted until the webhook secret has been verified.

The provider delivery key should use the most stable Gitea delivery identifier
available. When the provider omits a unique delivery id, AgentTeam derives an
idempotency key from the event type, repository, pull request number, action,
provider timestamp, and provider object id where present.

Gitea event normalization must preserve:

```text
pull request opened/reopened/synchronized/closed/merged
review and review comment activity where the payload supports it
issue comments associated with pull requests
failed commit status, workflow run, and workflow job updates
optional base branch push reminders for subscribed pull requests
provider URLs for messages and diagnostics
```

Non-failed CI states such as pending, running, or successful checks are ignored
unless a future product spec expands the noise policy.

## 7. Compatibility

Legacy Gitea watch ids, old trigger ids, and old run ids are handled by the
compatibility resolver. New Gitea runtime and storage paths use service actor
and service event models.