CI Watch & Auto-Fix
After Shep pushes the branch and opens the PR, it doesn’t walk away. Shep watches your CI. If checks fail, the agent reads the logs, fixes the problem, and pushes again.
How it works
Push → GitHub Actions runs → Shep watches every run and PR check
│
┌───────────────┴───────────────┐
│ │
Pass Fail
│ │
Merge gate Agent reads logs
│
Pushes a fix
│
▼
(loop, up to the attempt limit)CI watch runs whenever a feature pushes — that is, when push or PR is on for it. Shep uses gh to watch the workflow runs for the branch and the PR’s checks, polling every 30 seconds. When a check fails:
- Shep fetches the failing run’s logs (up to 50,000 characters by default).
- Shep gives them to the agent along with the feature’s context.
- The agent fixes the problem in the same worktree.
- Shep commits the fix and pushes again.
- CI runs again. If it passes, the feature moves on to the merge gate. If it fails again, repeat.
Shep watches GitHub Actions. A repo with no workflow files has nothing to watch, so it doesn’t hold up the merge. A PR with no checks counts as neutral.
Attempt limit
By default Shep makes up to 3 fix attempts. If CI is still failing after that, the run fails — the feature shows as Failed in the web UI, shep tui and shep feat status, with the reason.
To pick it up again once you’ve looked at the logs:
shep feat resume <id> # one feature
shep fleet retry --failed # every failed feature…or press Retry in the feature drawer, or R in shep tui.
Settings
CI watch is configured in the web UI under Settings → CI:
| Setting | What it controls | Default |
|---|---|---|
| Max fix attempts | Agent fix attempts before the run fails | 3 |
| Watch timeout | How long to wait for CI to finish | 10 minutes |
| Max log size | How much failure log text the agent gets | 50,000 characters |
| Poll interval | How often Shep checks GitHub | 30 seconds |
| Hide CI status | Hide CI badges in the drawer and Merge Review | — |
There’s no CLI flag for these; they apply to every feature.
To skip CI watch for a feature, create it without push or PR (--no-pr and no --push), or stop it after the PR is open with shep ps stop <id> or the drawer’s Stop button. The PR stays in draft for you to handle.
CI and the merge gate
A green CI run doesn’t merge anything by itself. The feature then waits at the merge gate for you to approve — unless you created it with --allow-merge, in which case Shep merges the PR once CI passes.
Shep only auto-merges on evidence. If the repo has workflows but Shep couldn’t observe a result, it treats CI as unverified and stops at the merge gate for a person, even with --allow-merge. Shep never auto-merges a PR whose CI failed.
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 — confusing for the agent; it may “fix” the wrong thing.
- Infra / network errors — not something the agent can fix. Repeated infra failures use up the attempts and fail the run.
The agent only sees the logs gh can fetch. If your CI hides errors behind a private job or an external dashboard, Shep can’t help with those — fix the visibility first.
Inspecting what Shep is doing
Each fix attempt shows up in the feature’s Log tab, in shep tui, and in:
shep feat logs <id> -f # follow the agent's log
shep feat status <id> # current state and reasonThe Activity tab shows how long each phase took, including the time spent in CI.
Tuning your project for auto-fix
- Clear error output. Tests that report what failed and why are easier to fix than tests that just say “FAIL”.
- Fast CI. Each attempt is one CI run. If CI takes 15 minutes, three attempts is 45 minutes.
- One concern per check. Small, focused checks are easier to diagnose than one big job.
- Deterministic tests. Flaky tests send the agent after the wrong problem.
What’s next
- Fleet management — retry every failed feature at once, and watch the failure rate.
- Configuration — where CI and workflow settings live.
- Spec-Driven Mode — add approval gates before the agent writes any code.