---
kind: task
slug: repo-setup-preflight
title: Connected repo setup preflight — readiness before automation
plan_slug: automation-foundation
epic_slug: connected-repos
status: draft
priority: P2
tenant_id: global
owner: unassigned
cursor_todo_id: null
updated_at: "2026-08-03"
---

# Task summary

**Repo Setup** tab on connected repos: verify a remote is automation-ready before orchestrator/worker dispatch (git access, default branch, CI permissions, required secrets).

## Description

**Benchmark:** Autensa v2.5.1 Repo Setup tab — preflight checks with in-UI fixes where the forge API allows. Echodo adapts this to multitenant `repo_links` and forge adapters (Forgejo + GitHub minimum).

### Preflight checks

| Check | Pass criteria |
|-------|---------------|
| Git clone | Shallow clone with stored credentials |
| Default branch | API-detected default matches stored value |
| Forge API | PR list/create permission |
| CI visibility | Latest workflow run status readable |
| Actions token (GitHub) | `contents` + `pull-requests` write if applicable |
| Required secrets | Names present (values never stored in Echodo DB) |

### UI

- Settings → Connected repos → per-repo **Setup** tab
- Traffic-light checklist with expandable failure reasons
- Block convoy **Go** when critical checks fail (soft warning vs hard block — configurable per workspace)

### Fixes (where API supports)

- GitHub: suggest/set workflow token permissions; link to docs for secret creation (do not write secret values through Echodo — operator pastes in forge UI)

## Dependencies

- Epic 3 connected repos (shipped)
- Epic 6 orchestrator should read preflight status before enqueue

## Subtasks

- [ ] `repoPreflightStatus` zod schema in `packages/shared`
- [ ] Forge adapter methods: `getDefaultBranch`, `listWorkflowRuns`, `getRepoPermissions`
- [ ] tRPC `connectedRepos.runPreflight`
- [ ] Settings UI Setup tab
- [ ] Orchestrator skips dispatch when repo link `preflight_ok` is false

## Estimation

L

## Acceptance criteria

- [ ] Repo with wrong default branch shows failing check with detected branch name
- [ ] Private repo without token shows auth failure (no silent pass)
- [ ] Preflight re-runnable without reconnecting repo
- [ ] No forge secret values persisted in Postgres

## Links

- Epic: `./Epic-connected-repos.md`