This commit is contained in:
DevRunbook release export
@@ -0,0 +1,148 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user