# 10 — Gitea integration

## Integration scope

The first Gitea adapter is read-only and supports repository discovery, capability detection, bounded evidence collection and profile generation. It must not create issues, branches, commits, pull requests, releases, webhooks or settings changes.

## Connection setup

Required fields:

- display name;
- HTTPS base URL, with explicit opt-in for private HTTP installations;
- access token;
- optional custom CA certificate strategy documented for private PKI;
- network access policy;
- request timeout.

After saving:

1. normalize base URL;
2. apply SSRF and DNS-rebinding protections;
3. call a lightweight version/user endpoint;
4. record server version and capabilities;
5. verify at least repository-read access;
6. encrypt token and discard plaintext;
7. show safe identity and permission summary.

## Permissions

Request the minimum read permissions supported by the connected Gitea version. Because Gitea installations and versions differ, the UI must explain required capabilities rather than assume one universal token-scope interface.

Never request admin access for ordinary repository discovery.

## Capability model

Capabilities are detected and stored, for example:

- repository list;
- repository metadata;
- branches and default branch;
- tags and releases;
- file content;
- branch protection visibility;
- issue and pull-request templates;
- Actions/workflow visibility;
- topics/languages;
- collaborators or permissions where allowed.

Each capability can be supported, unsupported, forbidden or temporarily unavailable.

## Adapter contract

```text
ForgeAdapter
  testConnection()
  getCapabilities()
  listRepositories(cursor, filters)
  getRepository(ref)
  listTree(ref, path, depthLimit)
  getFile(ref, path, sizeLimit)
  getBranches(ref)
  getTags(ref)
  getReleases(ref)
  getGovernanceEvidence(ref)
  getWorkflowEvidence(ref)
```

The internal contract is normalized and must not leak Gitea-specific payloads beyond the adapter package.

## Evidence collection boundaries

Default file allowlist:

- root README variants;
- `AGENTS.md` and nested instruction files discovered within depth limits;
- package/workspace manifests and lockfile identity, not entire lockfile content;
- common build/test configuration;
- Dockerfile and Compose manifests;
- CI workflow definitions;
- issue/PR templates;
- `.gitignore`, license and changelog;
- deployment manifests where explicitly selected.

Default denylist:

- `.env*` except example files after confirmation;
- private keys and certificates containing private material;
- secret manager exports;
- credential directories;
- binary blobs;
- large generated files;
- runtime data and database files;
- paths matching user-defined protected/excluded rules.

## Version strategy

At implementation time, use the connected server's version endpoint and current official Gitea API documentation. Maintain a capability matrix rather than scattering version comparisons through the code.

Unknown future versions should use optimistic capability probing with safe fallback, not be rejected solely for being newer.

## Synchronization

A synchronization job records stages:

1. connection and capability check;
2. repository metadata;
3. governance evidence;
4. bounded file evidence;
5. normalization;
6. findings;
7. snapshot commit.

Only the final transaction marks the snapshot complete. Raw API errors are mapped to safe codes such as:

- `AUTH_INVALID`
- `PERMISSION_MISSING`
- `CAPABILITY_UNSUPPORTED`
- `RATE_LIMITED`
- `NETWORK_BLOCKED`
- `TLS_ERROR`
- `REMOTE_UNAVAILABLE`
- `CONTENT_TOO_LARGE`

## Security

- outbound requests must block loopback, link-local, cloud metadata and disallowed private ranges unless the operator explicitly permits a private Gitea host;
- resolve and re-check DNS addresses across redirects;
- limit redirects and only allow HTTPS-to-HTTPS unless private HTTP is configured;
- never forward authorization headers across host changes;
- set timeouts and response-size caps;
- redact URL userinfo, query secrets and authorization headers;
- encrypt token values with a versioned application key;
- provide token rotation and connection deletion.

## UI states

- Healthy
- Degraded: one or more optional capabilities unavailable
- Authentication failed
- Permission limited
- Remote unavailable
- Disabled

A repository imported from Gitea remains usable as a local profile when the integration is disabled.

## Future write integration

Write actions require a separate scope and approval architecture. Potential later exports include creating an issue from a generated playbook or opening a branch/PR, but the adapter must never gain these methods through a casual extension of the read-only interface.