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
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
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 pending or running | wait and poll again |
gate and thespider-agent wait use different exit codes. gate2 means "not done yet." wait uses 3 for timeout and never emits 2. 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.