DevRunbook-Public/docs/10-gitea-integration.md

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

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.