48 lines
2.9 KiB
Markdown
48 lines
2.9 KiB
Markdown
|
---
|
||
|
|
name: repo-discovery-onboarding
|
||
|
|
classification: feature
|
||
|
|
success_metric: Operators can authorize GitHub or configure Forgejo/Gitea, discover their repositories, bulk-connect selected repos, import supported repository context, and receive usable agent onboarding instructions.
|
||
|
|
skip: []
|
||
|
|
status: open
|
||
|
|
created: 2026-09-25
|
||
|
|
model_policy:
|
||
|
|
roles:
|
||
|
|
role-conductor: claude-planning
|
||
|
|
role-architect: claude-planning
|
||
|
|
role-implementer: qwen-coder
|
||
|
|
role-reviewer: qwen-coder
|
||
|
|
escalate_to: claude-planning
|
||
|
|
---
|
||
|
|
|
||
|
|
# Repo discovery and onboarding
|
||
|
|
|
||
|
|
## Why
|
||
|
|
|
||
|
|
Echodo currently requires workspace admins to paste one remote URL at a time and reference a server-side token environment variable. That is adequate for worker execution but too cumbersome for onboarding a fleet of existing repositories.
|
||
|
|
|
||
|
|
The target flow is account/instance connection, repository discovery, explicit selection, context import, and agent setup. `plans/` remains the canonical product backlog; this convoy defines the implementation slices and gates.
|
||
|
|
|
||
|
|
## Scope and security decisions
|
||
|
|
|
||
|
|
- GitHub discovery uses the current user's linked Auth.js GitHub account and its server-side access token. The browser never receives the token.
|
||
|
|
- GitHub OAuth requests the minimum scopes needed for repository discovery. Existing accounts must explicitly re-authorize when their stored scope is insufficient.
|
||
|
|
- Forgejo/Gitea v1 uses an instance URL plus a **token environment-variable reference**. A PAT value is never stored in Echodo or sent back to the browser.
|
||
|
|
- Every tRPC procedure is workspace-scoped. Mutations require workspace owner/admin; discovery additionally verifies that the linked forge identity belongs to the current user.
|
||
|
|
- A connected repository remains a workspace resource. Importing repositories does not automatically create new workspaces.
|
||
|
|
- Repository context import is idempotent and records source repo/path/revision metadata. The canonical remote file is not silently overwritten by Echodo.
|
||
|
|
|
||
|
|
## Delivery order
|
||
|
|
|
||
|
|
1. **Forge discovery API** — shared schemas, credential resolution, paginated GitHub and Forgejo/Gitea discovery, and `connectedRepos.listAvailable`.
|
||
|
|
2. **Repo picker and batch connect** — searchable selection UI and transactional/idempotent bulk connection.
|
||
|
|
3. **Repository context ingestion** — import supported docs and existing convoy manifests with provenance and retryable status.
|
||
|
|
4. **Agent onboarding** — client-specific, copyable MCP setup based on the actual Echodo deployment model.
|
||
|
|
|
||
|
|
Briefs map 1:1 to the matching `plans/Plan-automation-foundation/Epic-repo-discovery-onboarding/Task-*.md` files so the worker can claim and complete backlog work.
|
||
|
|
|
||
|
|
## Gates
|
||
|
|
|
||
|
|
- Gate 1 must confirm the credential boundary above before Brief 1 is dispatched.
|
||
|
|
- Gate 2 reviews auth handling, tenant scoping, pagination, and redaction before merge.
|
||
|
|
- Live GitHub/Forgejo verification uses operator-provided test accounts; automated tests must use mocked HTTP responses and contain no tokens.
|