ProveAI Origin
Try it
cookbookbeginner6 min readUpdated 2026-05-27

Connect your repo to an agent

When Cursor pushes a PR, RJ needs to know which agent claims this repo. Claim a GitHub repo for one of your agents so every PR webhook resolves to the right snapshot suite.

Connect your repo to an agent

When Cursor (or Devin, Claude Code, or any coding-agent CI) pushes a PR, the RJ webhook arrives knowing only owner/repo. RJ needs to resolve that to a single agent so the right snapshot suite runs. Sprint 15 ships the per-repo claim system that makes that resolution explicit: one row in agent_repos, one agent per repo, no more "any agent owned by this user" guesswork.

Without a claim, the webhook returns 202 "no agent for this repo" and the PR check never appears. With a claim, every PR on that repo becomes a queued run on the named agent.

Setup

The agent_repos table landed in migration 0030. Two things must be true before you claim a repo:

  1. The RJ GitHub App is installed on the org/repo. If not, follow Wire RJ into GitHub Actions as a PR gate (Path A — GitHub App).
  2. The agent exists. Create it at /app/agents or via rj agents list to find an existing one.

Each (agent_id, repo_full_name) pair is unique while active. If you've already claimed the repo for another agent, archive that claim before claiming again.

Claim a repo — UI

Open /app/agents/[id]/settings, find the Integrations card, expand the GitHub section, click Add repo. Paste the owner/repo (e.g. rambo-01/runtime-judgement-app). Optional fields:

  • Base branch — restrict to PRs targeting one branch (e.g. main). Leave blank to accept PRs into any base branch.
  • Accept fork PRs — default on. Fork PRs run the suite but skip the check-run post (the fork doesn't have an installation token).

The claim appears in the integration card immediately. Every PR opened against that repo from now on triggers a run on this agent.

Claim a repo — API

curl -s -X POST https://runtime-judgement-app.vercel.app/api/agents/$AGENT_ID/repos \
  -H "Authorization: Bearer $RJ_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "repo_full_name": "rambo-01/runtime-judgement-app",
    "base_branch": "main",
    "accept_fork_prs": true
  }' | jq

Response on success (HTTP 201):

{
  "id": "01HZREPO...",
  "agentId": "01HZAGENT...",
  "repoFullName": "rambo-01/runtime-judgement-app",
  "baseBranch": "main",
  "acceptForkPrs": true,
  "createdAt": "2026-05-27T08:14:22.012Z"
}

Validation lives in app/api/agents/[id]/repos/route.ts — repo_full_name must match owner/repo (1–39 chars per side per GitHub's rules), base_branch is optional but cannot be the empty string (omit instead).

GET /api/agents/[id]/repos lists active claims. DELETE /api/agents/[id]/repos with { "repo_id": "..." } archives one — the row stays for audit; loadActiveClaims() filters by archived_at IS NULL.

Verify the wiring

After claiming, fire the webhook fixture against the agent's repo (full walkthrough in Wire RJ into GitHub Actions). The route now returns 200 {"runId":"..."} instead of 202 "no agent for this repo". Or from the CLI:

rj agents list

The agent row's GitHub-integration column shows the claimed repo count. From there, open /app/agents/[id]/settings/integrations to drill into each claim.

Fork-PR semantics

A fork PR fires the same pull_request webhook but the head repo doesn't have an RJ installation token. Two consequences:

  • The run still executes. RJ picks the suite, runs it against the trace data attached to the PR, and writes a verdict — same as a same-org PR.
  • No GitHub Check Run is posted. lib/github/pr-runs.ts marks the returned PrRunCreated with cannotPostCheckRun: true and the webhook route skips the postCheckRun() call. The verdict still surfaces at /app/runs/{runId} and in the agent's Runs tab; it just doesn't appear as a green/red dot on the PR itself.

To opt out entirely, set accept_fork_prs: false on the claim — fork PRs are dropped at the webhook before any compute is spent. Default is true because dogfood + cross-org collaboration are common.

Pitfalls

Two agents claim the same repo

The unique index agent_repos_unique_active on (agent_id, repo_full_name) WHERE archived_at IS NULL enforces one active claim per (agent, repo). But nothing stops you from claiming the same owner/repo for two different agents in the same workspace. The webhook handler picks the first active claim that matches; for multi-agent setups on the same repo, archive the losing claim or scope per branch via base_branch.

base_branch: "" rejected

The schema rejects the empty string explicitly to prevent the silent "all branches" footgun. Omit the field entirely if you don't want a branch restriction.

Claim works, webhook still 202s

Check the App is installed on the org the PR targets, not just the repo. GitHub Apps are installed per-org; the App needs pull_request event access on the repo. If the App is missing, wire-rj-into-github-actions.md Path A re-walks the install.

Check Run says PENDING forever

The verdict enum gained PENDING in migration 0030 so the orchestrator can flip the check status mid-stream. If the run never resolves, the orchestrator (Sprint 15) is the place to look — the webhook handler hands off via the run_triggered audit log.

Next steps

Related articles

Try it

AgentsSettings