Submatter/.convoys/repo-discovery-onboarding.md

name	classification	success_metric	skip	status	created	model_policy
repo-discovery-onboarding	feature	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.		open	2026-09-25	roles escalate_to role-conductor role-architect role-implementer role-reviewer claude-planning claude-planning qwen-coder qwen-coder 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.