PR gate
CI should not run models. A daemon on a box you control does that. CI only asks TheSpider whether the campaign passed.
pull request → TheSpider creates an incremental campaign
daemon → clones the commit, runs models, posts results
CI job → thespider-agent gate --campaign <id>
0 pass · 1 fail · 2 pending · 4 degraded
Webhook
Self-service GitHub connection is not in Cloud yet. TheSpider has to enable the hosted integration for a project. Do not try to wire a webhook secret by hand.
Once enabled, an opened or updated pull request creates an incremental campaign from the changed paths (paths only, not file contents).
Run the daemon
On a team box or self-hosted runner:
thespider-agent daemon --workdir /var/lib/thespider --models xai/grok-4.6
Set the project's repo_remote_url to a URL that user can clone with ssh-agent or an HTTPS helper. Never put a token in the stored URL.
Flags and the clone loop: The agent.
Poll from CI
CI needs a project-scoped TheSpider token. There is no gate-only scope yet.
thespider-agent gate --campaign <id>
# 0 pass · 1 fail (new findings) · 2 pending · 4 degraded
The CLI does not retry. CI should retry exit 2 with a delay until its own timeout.
| Exit | Meaning | Typical CI action |
|---|---|---|
0 | No new findings on the PR | allow merge |
1 | New findings on this branch (and, for incrementals, in changed_paths) | block |
2 | Work still outstanding — pending, running, or a failed slice that can still be retried | wait and poll again |
4 | Finished with no new findings, but part of the change was never audited: at least one slice failed every attempt (failed_slices), or was skipped because its model was disabled (skipped_slices) | block, then fix the cause and run thespider-agent repair, or re-enable the model and run again |
gate and thespider-agent wait use different exit codes. gate2 means "not done yet." wait uses 3 for timeout and never emits 2. Both use 4 for a degraded run. gate1 is any new finding; wait1 respects --fail-on (default critical,high). A triage of accepted or wont_fix quiets both. See Agent CLI contracts.2while it can still be retried. Once its attempts are spent (three by default, whether the model failed or the worker crashed) it stops being outstanding, and the gate settles on 4degraded instead of waiting forever. New findings still win: a degraded campaign with new findings is 1. So 0 means "no new findings and every slice was audited". Slices skipped by models disable are not retried and not outstanding either, so they let the campaign finish, but they count the same way: a finished campaign with skipped slices is degraded. A CI script that only treats pass as success blocks on degraded; that is intended.