RepoPilot

RepoPilot is built on AgentTeams v1.2.2 and focuses on safe, auditable repository maintenance automation. The default policy is pull_request_only: Agents may create branches, commits, and Pull Requests, but cannot auto-merge, delete branches, or modify permissions or secrets.

Two Automation Closed Loops

The PR review pipeline listens for opened, reopened, synchronize, and ready_for_review. Before every publication, the current head SHA is re-checked; if new commits arrive during review, the old Run is rejected. Comments carry a fixed <!-- repopilot-review --> marker, so each PR maintains exactly one RepoPilot comment without spamming duplicates.

Related MCP server: gts-repo-guardian

Flow Demo

The online Demo needs no model service or admin account. It replays the real delivery of repopilot-testbed#3 by default: the failing baseline reliably reproduces a concurrency race, RepoPilot fixes it with a Types + Store + Processor + Tests + Docs five-file patch, and creates PR #4 after GitHub Actions passes. The PR stays open; merge authority remains with humans.

<!-- repopilot-review -->

## RepoPilot PR Review

**Verdict:** NEEDS ATTENTION
**Reviewed revision:** `b504cec7c05cd2f3b84ee9c6ad7a3d3db6eead5c`

### Findings

| Severity | Finding                                | Location                          |
| -------- | -------------------------------------- | --------------------------------- |
| HIGH     | 发布前没有重新校验当前 head SHA        | `src/reviews/publisher.ts:19`     |
| MEDIUM   | 固定只扫描前 100 条评论                | `src/reviews/github-client.ts:43` |
| HIGH     | GitHub 写入失败仍记录“已发布” Evidence | `src/reviews/publisher.ts:31`     |

The following results come from public PR #5 with 5 files and 373 added lines; GitHub Actions CI has passed. RepoPilot still found 2 HIGH and 1 MEDIUM semantic issues from the real Diff and published a public Review Comment. The comment is generated by repopilot-reviewer using the pull-request-review Skill and published via repopilot_publish_review_comment. The tool validates the Run, repository, PR number, the running Reviewer Step, and the immutable head SHA, then appends review_publication Evidence on success. You can download the sanitized Run Proof JSON to verify the Run ID, Step, 8 Evidence entries, and the chain-head hash.

Maintenance Closed Loop

GitHub Issue / Failed CI
          │
          ▼
   Repo Lead 分诊与拆解
          │
          ▼
 Locator 根因定位 ──► Fixer 最小修复 ──► Verifier 独立验证
                                                │
                  人工审批 ◄── 高风险门禁 ◄─────┤
                                                │
                                                ▼
                                      Archivist 沉淀 Runbook

GitHub Pull Request
          │
          ▼
 Reviewer 固化 head SHA ──► 分页读取 Diff / Checks ──► 更新托管 Review Comment

Every key stage writes decisions, tool calls, Git references, CI results, and approval events into a PostgreSQL append-only SHA-256 evidence chain, and supports replay through OpenTelemetry Traces and the evidence console.

Proof-Carrying Pull Request

RepoPilot does not treat "auto-generated PR" as the end point; instead, every PR carries a machine-verifiable Proof Bundle:

Run 身份 + AgentTeams Step 时间线 + Skill 版本
         + 工具与决策 Evidence + Git / CI 引用
         + 审批历史 + SHA-256 链根 + 确定性质量门禁

curl http://127.0.0.1:3000/api/v1/runs/<run-id>/proof \
  --output artifacts/proof-bundle.json
pnpm build
pnpm evaluate artifacts/proof-bundle.json artifacts/evaluation-report.json

The Proof Score measures proof completeness and does not pass off control-plane tests as model fix quality; patch correctness is still judged by the public testbed, the independent Verifier, and GitHub Checks.

After the Runbook archive completes, the Archivist calls repopilot_publish_proof_comment to idempotently publish the sanitized completeness results, Agent/Skill execution results, and the SHA-256 chain root to the corresponding PR. Repeated runs update the same comment, so the Proof is truly delivered with the PR rather than existing only in the control-plane API.

Why RepoPilot

AgentTeam

The full Agent Identity definitions live in deploy/agentteams/repopilot-team.yaml, and the Skill contracts live in skills/.

Core Capabilities

MCP Registry

RepoPilot provides a reproducible entry point for the MCP Registry's static checks and hosted publication:

MCP tool discovery needs no model or GitHub credentials; only database or GitHub read/write tools depend on the corresponding runtime services and Secrets at call time. The full deployment contract is in docs/deployment.md.

System Architecture

flowchart LR
    GH[GitHub Issue / Failed CI / Pull Request] --> CP[RepoPilot Control Plane]
    CP --> DB[(PostgreSQL + pgvector)]
    CP --> MX[Matrix Admin → Manager DM]
    MX --> M[AgentTeams Manager]
    M --> TL[Repo Lead]
    TL --> L[Locator]
    TL --> F[Fixer]
    TL --> V[Verifier]
    TL --> A[Archivist]
    M --> R[Reviewer]
    L & F & V & A --> MCP[RepoPilot MCP via Higress]
    R --> MCP
    MCP --> GHAPI[GitHub REST API]
    MCP --> DB
    DB --> UI[Evidence Console]
    CP --> OTEL[OTLP / AgentLoop / LoongSuite]

More design details are in docs/architecture.md.

Project Structure

RepoPilot/
├── apps/
│   ├── control-plane/       # Fastify REST / Webhook / MCP / 审批 / 证据账本
│   └── console/             # 飞行记录器风格 React 证据控制台
├── packages/contracts/      # Zod Schema、共享类型和显式状态机
├── deploy/agentteams/       # AgentTeams v1.2.2 Worker / Team 清单
├── skills/                  # 6 个可复用 RepoPilot Skills
├── evaluation/              # Proof Bundle 协议与可靠性 Benchmark
├── scripts/                 # Skill 校验、可靠性基线与离线评测
├── docs/                    # 架构、安全、部署和 Demo 文档
├── CONTRIBUTING.md          # 开发流程、质量门禁与贡献规范
├── Dockerfile               # Streamable HTTP Control Plane 生产容器
├── glama.json               # Glama MCP Registry 维护者声明
├── API.md                   # REST / Webhook / MCP 出入参
├── Method.md                # 外部 SDK、HTTP Method 与调用契约
└── docker-compose.yml       # PostgreSQL 16 + pgvector

Quick Start

Prerequisites

• Node.js 20+

• pnpm 9+

• Docker Desktop / Docker Engine

Model credentials are not a prerequisite for building, testing, or running the local control plane.

git clone https://github.com/wellkilo/RepoPilot.git
cd RepoPilot
cp .env.example .env
docker compose up -d postgres
pnpm install --registry=https://registry.npmjs.org
pnpm build
pnpm --filter @repopilot/control-plane start

Open the console:

http://127.0.0.1:3000

You can also use one-click initialization:

./init.sh

Production Container

The root Dockerfile builds the Console, shared contracts, and Control Plane, and starts the same production process as a non-root user:

docker build -t repopilot:local .
docker run --rm -p 3000:3000 \
  -e DATABASE_URL=postgres://repopilot:repopilot@host.docker.internal:5432/repopilot \
  -e GITHUB_ALLOWED_REPOSITORIES=wellkilo/repopilot-testbed \
  repopilot:local

MCP clients connect to http://127.0.0.1:3000/mcp. When GitHub reads or writes are needed, inject GITHUB_TOKEN via runtime Secrets; the image contains no credentials.

stdio MCP

When a Registry or local MCP client needs stdio, first generate the standalone runtime package, then start the root entry point:

pnpm glama:build
pnpm glama:verify
node mcp-server.mjs

glama:verify performs a real MCP initialization and validates the 15 tools in an environment without database or GitHub credentials. Tool discovery does not connect to external services; real services and credentials are still required when actually executing data or GitHub operations.

Creating Your First Run

curl -X POST http://127.0.0.1:3000/api/v1/runs \
  -H 'Content-Type: application/json' \
  -d '{
    "source": {
      "type": "github_issue",
      "repository": "wellkilo/repopilot-testbed",
      "issueNumber": 1
    },
    "executionPolicy": "pull_request_only"
  }'

To read GitHub Issues, configure GITHUB_TOKEN in the local .env. If no AgentTeams Matrix is configured, the Run stops at awaiting_dispatch and does not fake execution results with Mock Agents.

After binding the repository Webhook's Pull requests events, creating, reopening, pushing new commits to, or marking a non-Draft PR as ready for review all trigger an independent review Run. The Reviewer reads the PR, paginated diff, and Checks, and idempotently creates or updates a single RepoPilot PR Review comment; if the PR gains new commits during review, the old Run is rejected for publication due to a head SHA mismatch.

Real AgentTeams Collaboration

Real Agent reasoning requires an OpenAI-compatible model endpoint, such as:

• Managed services like Alibaba Cloud Bailian;

• Other OpenAI-compatible APIs;

• Local compatible endpoints like Ollama.

Model keys are only given to AgentTeams/Higress; they never enter RepoPilot source code, the database, or deployment manifests.

Deployment docs:

• docs/deployment.md

• deploy/agentteams/README.md

Reproducible Testbed

The testbed contains a deterministic concurrency defect: two requests for the same GitHub delivery can simultaneously pass through the find / save window, creating two tasks and executing dispatch twice. RepoPilot consolidates create-or-reuse into DeliveryTaskStore.getOrCreate, so the same delivery shares a single in-flight Promise, and adds sequential retries plus a negative control for different deliveries. The PR remains open for review and does not trigger auto-merge.

The PR Review Demo uses the separate public PR #5: the code compiles, and all 5 tests plus GitHub Actions pass, but the Reviewer does not equate green CI with correct code. It reads the 5 changed files page by page, identifies three semantic defects on the pinned revision b504cec — stale SHA, comment pagination, and failed Evidence — and publishes the same hosted comment through the real GitHub REST API. The review_publication record of that Run and the 8-entry hash-chained Evidence have been redacted and exported to docs/assets/demo/pr-review-run.json.

Verification

pnpm typecheck
pnpm benchmark:reliability
pnpm skills:validate
pnpm lint
pnpm format:check
pnpm build

The current control-plane reliability baseline is 52/52. Tests cover state machines, webhook signature verification, evidence hashing, database immutability triggers, delivery concurrency idempotency, approval versions with single-use consumption, Agent Skill Step lifecycle, Proof Bundle integrity checks, PR Review provenance with stale SHA protection, HTTP conflict semantics, and console labels. CI generates structured JSON reports.

Security Boundaries

The detailed threat model and production hardening items are in docs/security.md.

Documentation Navigation

Current Boundaries

• Without a configured model service, real AgentTeams inference cannot complete; build, tests, control plane, and testbed are unaffected.

• The Runbook defaults to PostgreSQL full-text search; vector(1536) is reserved for semantic recall.

• AgentLoop Recall is an optional capability and degrades automatically to the local Runbook when no credentials are available.

• Console approval identity is currently demonstrated via a trusted reverse-proxy Header; production must integrate OIDC/SSO.