---
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.