Skip to Content
GuidesCI Watch & Auto-Fix

CI Watch & Auto-Fix

After Shep pushes the branch and opens the PR, it doesn’t walk away. Shep watches your CI pipeline. If checks fail, the agent reads the logs, diagnoses the problem, and pushes a fix.

Shep iterating on a feature with the agent fixing issues

How it works

Push   →   GitHub Actions starts   →   Shep watches checks
                                              │
                              ┌───────────────┴───────────────┐
                              │                               │
                            Pass                             Fail
                              │                               │
                       PR ready for review            Agent reads logs
                                                              │
                                                       Pushes a fix
                                                              │
                                                              ▼
                                              (loop, up to retry limit)

Shep polls GitHub for check status. When a check fails:

  1. Shep fetches the run logs.
  2. Shep extracts the relevant error output (failing test name, lint error, build error).
  3. Shep gives this to the agent along with the original feature context.
  4. The agent makes a fix in the same worktree.
  5. Shep commits the fix and pushes again.
  6. CI runs again. If it passes, you’re done. If it fails again, repeat.

Retry limits

By default Shep retries up to 3 times per failure mode. After that the feature enters Blocked state and waits for you. You’ll see it highlighted in the dashboard.

Override the retry count globally:

shep settings workflow
# answer the "How many CI fix retries before pausing?" question

Or in .shep/config.json:

{
  "agents": {
    "retryAttempts": 5
  }
}

What CI Shep can fix

It works best when CI errors are clear and reproducible. In practice:

  • Failing tests — usually fixable, especially when the test message names what failed.
  • Lint / format errors — almost always fixable.
  • Type errors — usually fixable.
  • Build errors — usually fixable.
  • Flaky tests — Shep retries once. If the test passes, great. If it consistently fails, the feature pauses.
  • Infra / network errors — Shep is not a CI debugging tool. Repeated infra failures pause the feature.

The agent only sees the logs Shep can fetch. If your CI hides errors behind a “private” job or a custom dashboard, Shep can’t help with those — fix the visibility first.

Disabling CI watch

If you want CI to be entirely your responsibility:

shep settings workflow
# answer the "Watch CI after push?" question with "no"

Or per-feature: there isn’t a --no-ci-watch flag, but you can stop CI watch by stopping the agent (shep agent stop <id>) once the PR is open. The PR stays in draft for you to handle.

Inspecting what Shep is doing

In the dashboard, the activity log shows every CI poll, every retry, every fix attempt:

14:32:01  push          feat/add-health-endpoint
14:32:18  ci-start      check_run_id=8294
14:33:42  ci-fail       jobs.test failed: "expected 200 but got 500"
14:33:43  agent-fix     reading logs, asking agent for fix
14:34:09  push          fix(test): handle missing version env var
14:34:25  ci-pass       all checks green
14:34:25  pr-ready      shep-ai/my-app#142

shep feat logs <id> shows the same stream from the terminal.

Tuning your project for auto-fix

A few things make Shep’s auto-fix more reliable:

  • Clear error output. Tests that report what failed and why are easier to fix than tests that just say “FAIL”.
  • Fast CI. Each retry is one CI run. If your CI takes 15 minutes, three retries is 45 minutes. Optimize CI speed.
  • One concern per check. A single check with 50 unrelated tests is harder to fix than smaller checks with focused responsibilities.
  • Deterministic tests. Flaky tests confuse the agent — it’ll fix the wrong thing.

What happens after auto-fix succeeds

Same as a manual fix push: CI passes, the PR is ready for review, and Shep moves the feature to the Review phase.

If you set --allow-merge, Shep merges the PR automatically once CI is green. Otherwise the PR sits in draft for you to mark ready and merge.

ConfigurationSpec-Driven Mode