Skip to content

deployment.md

Latest commit

 

History

History
230 lines (179 loc) · 8.6 KB

deployment.md

File metadata and controls

230 lines (179 loc) · 8.6 KB
Raw

Deployment

Local Control Plane

Requirements:

  • Node.js 20+
  • pnpm 9+
  • Docker
cp .env.example .env
docker compose up -d postgres
pnpm install --registry=https://registry.npmjs.org
pnpm build
set -a
source .env
set +a
pnpm --filter @repopilot/control-plane start

The server binds HOST and PORT, serves /health, REST, /mcp, and the built console in one process.

Production Container

The root Dockerfile is the canonical production container entrypoint. It builds all workspace packages, installs only the deployed Control Plane dependencies, copies the Console assets, preserves the project license, and runs as the unprivileged node 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

The image declares PORT=3000 and starts with node dist/main.js. DATABASE_URL is required for data operations and health checks. GITHUB_TOKEN remains optional during MCP discovery, but is required before calling GitHub-backed tools. Supply every credential at runtime; never bake secrets into the image.

Validate MCP discovery:

curl http://127.0.0.1:3000/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

The response contains 15 tools with parameter descriptions and MCP safety annotations. The root glama.json identifies the GitHub maintainer.

stdio MCP

The Control Plane package also builds dist/mcp-stdio.js. It registers the same 15 tools and real dependencies as the HTTP server, but communicates over stdin/stdout instead of starting Fastify. Build the self-contained hosted runtime and verify its real process contract with:

pnpm glama:build
pnpm glama:verify

The build writes the production package to .glama/server; node mcp-server.mjs loads only that package. The generated directory is intentionally ignored by Git and must be produced during the container build.

MCP discovery is intentionally lazy: initialize and tools/list do not connect to PostgreSQL or GitHub. Actual tool calls still require the real backing services and credentials. There is no mock provider or in-memory production fallback.

Glama Hosted Release

Glama creates its own Dockerfile from the server admin form; it does not consume the repository's root Dockerfile directly. Configure the claimed server under /admin/dockerfile with these exact values:

Field Value
Node.js version 22
Build steps ["corepack enable && corepack prepare pnpm@9.15.9 --activate && pnpm install --frozen-lockfile --registry=https://registry.npmjs.org && pnpm glama:build"]
CMD arguments ["node","mcp-server.mjs"]
Pinned commit SHA Leave empty to build the latest default-branch commit, or set it to the exact commit that contains mcp-server.mjs.

The Glama runner wraps the CMD with mcp-proxy --, so the target must be a stdio MCP process. Keep Build steps as one JSON-array element joined by &&: Glama executes separate elements as separate Docker layers. Do not point CMD at apps/control-plane/dist/mcp-stdio.js; the stable root launcher and self-contained package prevent stale workspace output from passing the image build and then failing at process startup.

Use this environment-variable JSON Schema:

{
  "type": "object",
  "properties": {
    "DATABASE_URL": {
      "type": "string",
      "description": "PostgreSQL connection URL required when a data-backed tool is called."
    },
    "GITHUB_TOKEN": {
      "type": "string",
      "description": "Fine-grained GitHub token required when a GitHub-backed tool is called."
    },
    "GITHUB_ALLOWED_REPOSITORIES": {
      "type": "string",
      "default": "wellkilo/repopilot-testbed",
      "description": "Comma-separated repository allowlist in owner/name form."
    }
  },
  "additionalProperties": false
}

Do not mark DATABASE_URL or GITHUB_TOKEN as required for the Build Test. Glama uses placeholder credentials during discovery; the stdio process can list tools without opening those connections. Before deploying, confirm the generated Dockerfile preview checks out the intended commit. After the Build Test succeeds, create a semantic release such as 0.3.0.

Database Migration

Fresh Docker volume automatically runs:

apps/control-plane/sql/001_init.sql
apps/control-plane/sql/002_approval_consumption.sql
apps/control-plane/sql/003_step_idempotency.sql
apps/control-plane/sql/004_pull_request_source.sql
apps/control-plane/sql/005_step_cancellation.sql

从旧版 RepoPilot 升级已有数据库时，001_init.sql 已执行过，不要重复运行；后续迁移 均使用 IF NOT EXISTS 或等价保护：

psql "$DATABASE_URL" -v ON_ERROR_STOP=1 \
  -f apps/control-plane/sql/002_approval_consumption.sql
psql "$DATABASE_URL" -v ON_ERROR_STOP=1 \
  -f apps/control-plane/sql/003_step_idempotency.sql
psql "$DATABASE_URL" -v ON_ERROR_STOP=1 \
  -f apps/control-plane/sql/004_pull_request_source.sql
psql "$DATABASE_URL" -v ON_ERROR_STOP=1 \
  -f apps/control-plane/sql/005_step_cancellation.sql

0.3.0 将 MCP 工具 github_get_pull_request_checks 统一更名为 github_list_pull_request_checks。升级后应同步更新 Agent Skill 或客户端工具白名单； 服务端不保留旧别名，以避免重复工具和不一致的 get / list 集合命名。

AgentTeams

Install AgentTeams v1.2.2 using its official installer or Helm chart. Model service credentials are supplied to AgentTeams, not RepoPilot.

Example OpenAI-compatible configuration:

Base URL: http://host.docker.internal:11434/v1
API Key: ollama
Model: qwen3

The exact local model must support the AgentTeams runtime requirements. Use a hosted model when local resources cannot provide stable tool use and context capacity.

Then render:

export AGENTTEAMS_MODEL=qwen3.5-plus
export AGENTTEAMS_COPAW_WORKER_IMAGE=higress-registry.cn-hangzhou.cr.aliyuncs.com/agentteams/agentteams-copaw-worker:v1.2.2
export REPOPILOT_MCP_URL=https://agentteams.example.com/mcp-servers/repopilot/mcp
envsubst < deploy/agentteams/repopilot-team.yaml > /tmp/repopilot-team.yaml
agt apply -f /tmp/repopilot-team.yaml

RepoPilot uses AgentTeams v1.2.2's default CoPaw Worker runtime. QwenPaw is opt-in in this release and is not part of the reproducible deployment path.

GitHub Webhook

Configure repository webhook:

  • URL: https://<repopilot>/api/v1/webhooks/github
  • Content type: application/json
  • Secret: same as GITHUB_WEBHOOK_SECRET
  • Events:
    • Issues
    • Workflow runs
    • Pull requests

GitHub Token Permissions

RepoPilot 建议使用仅限目标仓库的 fine-grained personal access token 或 GitHub App。 最小权限为：

  • Contents: Read and write：推送修复分支；
  • Pull requests: Read and write：创建 PR；
  • Issues: Read and write：创建或更新 PR 的 Proof Comment 与 Review Comment；
  • Actions: Read 与 Checks: Read：读取独立验证结果。

不要授予仓库管理、密钥管理或组织管理权限。GITHUB_ALLOWED_REPOSITORIES 仍会在 应用层限制可操作仓库。

Observability

Set:

OTEL_EXPORTER_OTLP_ENDPOINT=https://<collector>:4318
OTEL_SERVICE_NAME=repopilot-control-plane

RepoPilot 输出 HTTP、编排、MCP 工具、持久化 Agent Skill 和端到端 Run Span， 同时输出操作、Skill 与 Run 的计数器和时延直方图。Trace 与 Metrics 共享 runId、stepId、Agent、Skill、repository 和 outcome 属性。AgentTeams/AgentLoop 可补充模型运行轨迹；Evidence 仍是持久化、哈希链接的事实源。

导出一个 Run 并离线复评：

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