Dedicated runtime adapters
Work a station through GitLab CI/CD, CircleCI, Buildkite, Cursor, Jules or GitHub Copilot with the vendor's own API, a credential you create and explicit state mapping.
Beside the generic kinds on external worker runtimes, six runtimes have a dedicated adapter. Each one starts a run over the vendor's own documented API, polls its state, maps every documented vendor state to running, pass, fail or blocked, extracts artifacts, enforces a deadline, and cancels at the vendor where the vendor documents a cancel.
Add one under Factory settings → Runtimes. Each kind has typed settings, an encrypted credential, Test credentials, a table of the vendor states and how each is read, and, for the CI kinds, a ready-to-commit pipeline file.
The six kinds
| Kind | Start | Stop on a CodeBook-side end | How the brief arrives |
|---|---|---|---|
| GitLab CI/CD (GitLab.com or self-managed) | Creates a pipeline on a ref with variables | Pipeline cancel | Four CI variables; the pipeline fetches the brief |
| CircleCI (cloud or server) | Triggers a pipeline on a branch with parameters | Workflow cancel (running workflows only) | Four parameters, each checked against CircleCI's 512-character limit |
| Buildkite | Creates a build with environment variables | Build cancel | Four environment variables; the build fetches the brief |
| Cursor cloud agent | Creates an agent with the prompt, repositories, model and auto-PR setting | Cancel (an already-finished run is treated as finished) | The brief is the prompt |
| Jules | Creates a session with automatic pull requests and no plan approval | None documented — recorded as unsupported | The brief is the prompt |
| GitHub Copilot (agent tasks API, public preview) | Creates a task that creates a pull request | None documented — recorded as unsupported | The brief is the prompt |
Every call refuses redirects, times out after 20 seconds and caps the body at 2 MB. A self-managed base URL (GitLab, CircleCI server) is checked against the private-network guard on every request, because the credential travels with it. A 429, or GitHub's documented secondary limit, is read as a rate limit with the vendor's own wait, and the next poll is pushed out accordingly.
CI pipelines fetch the brief
A CI run receives four small values: CODEBOOK_JOB, CODEBOOK_BRIEF_URL, CODEBOOK_CALLBACK_URL and a single-use CODEBOOK_CALLBACK_TOKEN. The pipeline fetches the brief from CodeBook with that token, which is only valid while the run is out with the runtime, and answers through the callback. Reading the brief does not use the token up; answering does.
CodeBook also polls the vendor, so a pipeline that dies without reporting still ends with the vendor's own verdict. CI states that wait for a person — GitLab manual, CircleCI on_hold, Buildkite blocked — keep waiting rather than failing.
Coding agents get the brief as the prompt
Cursor, Jules and Copilot receive the brief as their prompt and no token: the adapters cannot rely on reaching CodeBook from the vendor's sandbox. Agents are asked to end with CODEBOOK_OUTCOME: pass|fail|blocked. A finished agent that states no outcome passes only if it opened a pull request, with a note saying so; otherwise it is blocked. Agent states that wait for a person — Jules awaiting feedback or paused, Copilot waiting for user — are blocked.
Pull requests opened by Cursor and Jules are recorded as pull-request artifacts on the card. Copilot's task answer carries an ID but no pull request URL, so the task page is linked and no pull-request artifact is invented. Pipeline, build and task links are kept on the run.
States and stopping
The adapter lists every documented vendor state explicitly, and the settings page shows the list. A state that is not listed is treated as still running, and the deadline ends it.
A run that the vendor or its callback answered is marked as not needing a stop. A run that CodeBook ended first — a person's cancel, the card leaving the station, or the deadline — is cancelled once at the vendor where a cancel is documented. Jules and Copilot document none, and the run records that cancellation was not propagated. A cancel that is rate-limited is retried after the wait. A callback and a poll that race finish the run once.
The factory policy's switch for outside runtimes is checked before anything is sent to any vendor.
Not built
- OpenAI Codex cloud, Amp and Factory droids have no documented API that starts a run with an API key (Codex starts from ChatGPT or its CLI; Amp's API cannot start a thread; Factory's Sessions API is enabled for selected organizations only). They connect by MCP pull, like Claude Code and Kiro.
- Cancellation at GitHub Actions and Devin on a CodeBook-side cancel is unchanged: not propagated.
- Cursor webhooks exist only in the legacy API, so Cursor is polled.
- Idempotent starts: none of the six documents an idempotency key. A crash between the vendor accepting a run and CodeBook saving it can leave an orphaned vendor run.
- The adapters are written against the vendor documentation and tested against local stand-ins that assert the exact requests. No call has been made to a real vendor with customer credentials.