ShipRepo Docs

An AI engineer that reads your repo, fixes the bug, runs tests in a sandbox, and opens a pull request. This page covers every knob.

Quickstart

1. Sign in at cp.shiprepo.com using Melyx SSO. No separate signup — one account covers ShipRepo, cart, and future Melyx apps.
2. Paste a public GitHub repo URL on the dashboard. For example https://github.com/expressjs/express.
3. Describe the change in plain English — "fix the memory leak in LiveFeed when unmounted".
4. Wait 60–180 seconds. Free tier shows a diff preview. Paid opens a real PR.
5. Review the diff, rate the result, or click Approve & create PR to promote a preview to a paid PR run.

How it works under the hood

Every task runs through the same pipeline:

clone → Planner → Locator (grep + import graph) → Inspector
      → Fixer (single / best-of-N) → Reviewer
      → Validator (install · typecheck · lint · security · test)
      → debug loop (up to 2 retries, escalate to stronger model)
      → Git commit · push · PR (if GitHub connected)
      → save repo memory + accepted diff for next run

Each stage writes a row to task_logs, visible in real time on the task page or via the SSE endpoint.

Plans & limits

Rate limit: 20 task submissions per minute per account across all plans.

Fix a bug

From the dashboard: click + New task, paste the repo URL, describe the fix. ShipRepo picks the right file (or up to 3 files for paid), generates a minimal patch, and runs your test suite inside a Docker sandbox.

Describe in plain English — the more specific, the better. Include the error if you have one:

✅ "fix the 500 in POST /signup when email is missing — see logs, TypeError: cannot read 'toLowerCase' of undefined"

❌ "make signup better"

Scaffold a marketing site

From cp.shiprepo.com/scaffold.html: describe a brand and a brief. ShipRepo generates 7 pages (landing, features, pricing, about, docs, terms, privacy) with a consistent nav, Tailwind theme, and deploys them automatically.

Repo URL is optional. Leave it blank to get a free live URL only. Provide one and the generated files are also pushed and a PR is opened.

Ship to a new GitHub repo

On any scaffold result page, click 📦 Ship to new GitHub repo. Enter a name, choose public or private. ShipRepo uses your connected GitHub token to create the repo and push the generated files as the initial commit.

Ship to web (free live URL)

Every scaffold task automatically deploys to https://shiprepo.com/s/<slug>/. No DNS, no CDN, no config. Use it for demos, previews, client review.

Human approval gates

For risky tasks, set approval_mode: "manual" when creating a task (or in the settings UI). The pipeline pauses twice:

• After Planner — status becomes awaiting_plan. Review the step list, then call POST /v1/tasks/{id}/approve with {stage: "plan"}.
• After Fixer — status becomes awaiting_diff. Review the generated diff, then approve with {stage: "diff"}.

Each gate has a 5-minute timeout. If unapproved, the task is cancelled and no credits are consumed.

Rate a result

On the result page, rate 1–5 stars and mark whether the fix was correct. Feedback is saved to task_feedback and feeds the repo-memory learning loop. Your ratings tune your future runs — we don't share them.

Connect GitHub

Without a connected token, ShipRepo can only read public repos and preview diffs. To open real PRs or push scaffolded code, connect GitHub:

1. From the dashboard, click the yellow 🔗 Connect GitHub banner (top of the page).
2. Authorize ShipRepo on GitHub. We request repo and read:user scope only.
3. You're redirected back. Your token is encrypted with AES-256-GCM and only decrypted by the worker at task time.

Revoke any time from github.com/settings/applications.

BYOK — bring your own model key

Go to cp.shiprepo.com/byok.html.

Supported providers

Security

• Keys are encrypted AES-256-GCM at rest and never returned over the API after creation.
• Only the worker decrypts keys, only during your own tasks.
• Raw chat access isn't exposed — you can't use ShipRepo as a model proxy.
• Click Test key before saving — ShipRepo hits /models on the provider to verify.

Webhooks

ShipRepo calls your webhook when key events happen (coming soon — task.done, task.failed, pr.merged). Configure a URL in your account settings and we POST a signed JSON payload.

API — authentication

Create a personal access token at cp.shiprepo.com/tokens.html. Send it on every request:

Authorization: Bearer sr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Tokens can be revoked at any time. Scoped tokens (read-only / write) are on the roadmap.

API — tasks

Create a task

POST https://api.shiprepo.com/v1/tasks
Authorization: Bearer sr_...
Content-Type: application/json

{
  "repo_url": "https://github.com/acme/app",
  "prompt":   "fix login bug when user.email is undefined",
  "base_branch": "main",
  "task_type": "fix"
}

Response includes the queued task id, mode (preview or pr), and plan context. For task_type: "scaffold", repo_url is optional.

Get a task + step logs

GET https://api.shiprepo.com/v1/tasks/{id}
Authorization: Bearer sr_...

→ { "task": {...}, "logs": [ { step, status, output, created_at }, ... ] }

Your limits

GET /v1/tasks/limits
→ { "limits": {...}, "used_this_month": 12, "plan": "pro", "use_byok": false }

Other task endpoints

API — streaming logs (SSE)

Watch a task live. Great for CLIs and terminal UIs.

GET https://api.shiprepo.com/v1/tasks/{id}/logs/stream
Accept: text/event-stream

→ event: log      · { step, status, output, ... }
  event: state    · { status, pr_url, deployed_url, cost_usd }
  event: end      · { status }

The stream closes when the task finishes. Ping is implicit (state events every ~1.5s).

API — export your data

GET /v1/me/training/summary
GET /v1/me/training/export.jsonl     # JSONL of your done tasks + diffs + ratings

Exports everything you've done so you can fine-tune your own model later. Your data, your file.

OpenAPI spec

The full machine-readable spec is published at api.shiprepo.com/openapi.yaml. Browse an interactive Swagger UI at api.shiprepo.com/docs.

CLI & curl

cURL

curl -X POST https://api.shiprepo.com/v1/tasks \
  -H "Authorization: Bearer $SHIPREPO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo_url":"https://github.com/acme/app","prompt":"fix login bug"}'

Node.js

const res = await fetch("https://api.shiprepo.com/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SHIPREPO_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    repo_url: "https://github.com/acme/app",
    prompt: "fix login bug",
  }),
});
const task = await res.json();
console.log("Task:", task.id);

Python

import os, requests
r = requests.post(
  "https://api.shiprepo.com/v1/tasks",
  headers={"Authorization": f"Bearer {os.environ['SHIPREPO_TOKEN']}"},
  json={"repo_url": "https://github.com/acme/app", "prompt": "fix login bug"},
)
print(r.json())

GitHub Action (recipe)

name: Triage with ShipRepo
on:
  issues:
    types: [labeled]

jobs:
  fix:
    if: github.event.label.name == 'shiprepo'
    runs-on: ubuntu-latest
    steps:
      - name: Submit task
        env:
          SHIPREPO_TOKEN: ${{ secrets.SHIPREPO_TOKEN }}
        run: |
          curl -fsS https://api.shiprepo.com/v1/tasks \
            -H "Authorization: Bearer $SHIPREPO_TOKEN" \
            -H "Content-Type: application/json" \
            -d "{\"repo_url\":\"https://github.com/${{ github.repository }}\",\"prompt\":\"${{ github.event.issue.title }} — ${{ github.event.issue.body }}\"}"

CI integration tips

• Store your SHIPREPO_TOKEN in CI secrets, never in code.
• Poll /v1/tasks/{id} every 2–5s, or stream via the SSE endpoint.
• Block the CI job on status === "done" and fail if pr_url is missing.
• Use approval_mode: "manual" for production repos so a human approves each diff before it becomes a PR.

Sandbox

Every task runs in a throwaway Docker container with these guarantees:

docker run --rm \
  --network=none \
  --user 1000:1000 \
  --read-only \
  --tmpfs /tmp:rw,exec,size=200m \
  --cap-drop=ALL \
  --security-opt=no-new-privileges:true \
  --memory=512m --cpus=1 --pids-limit=200 \
  -v /tmp/shiprepo-tasks/<id>:/workspace \
  node:20-alpine

No network, no host filesystem, no capabilities, no root. Container is destroyed after every task. Our VPS filesystem cannot be read or modified from inside.

Stack auto-detection

Stages run in order. The first failure is fed back to the debug loop with exact output.

Agents & retry

• Planner — splits the task into 1–5 atomic steps.
• Locator — grep + import-graph expansion, picks up to 3 candidate files.
• Inspector — LLM selects the exact file(s) and root cause.
• Fixer — writes the patch. Pro/Scale retries use best-of-N (3 candidates, pick the shortest that compiles).
• Reviewer — LLM checks minimality + syntax + edge cases before Validator.
• Validator — runs the full verification pipeline in the sandbox.
• Debug loop — on test fail, sends the error to Fixer for up to 2 retries. The final retry escalates to a stronger model.

Repo memory

After every merged PR, ShipRepo extracts the repo's conventions (TypeScript strict? camelCase? Jest vs vitest?) and stores them in repo_memory. The accepted diff is saved to repo_past_patches. Next time you submit a task on the same repo, the Fixer is few-shotted with 1–2 past accepted diffs and the convention summary. The more you use ShipRepo, the better it gets on your code.

Common errors

FAQ

Support

Email hello@shiprepo.com — median response under 12h on weekdays. Paid plans jump the queue.