149 lines
4.7 KiB
Markdown
149 lines
4.7 KiB
Markdown
# 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.
|