Skip to main content
A build turns one commit of your repository into a version that can serve. It runs nine stages in order, and a failure at any of them stops the build, says which stage and why, and changes nothing that is live.

​
What starts a build

  • Creating an agent: the first deploy.
  • Deploy on the agent’s page: triggered manually, at the head of the agent’s branch.
  • A push to the agent’s branch, with automatic deploys on: triggered by push. See Automatic deploys.
  • A configuration change, with automatic deploys on: triggered by a configuration change.

​
The stages

Each stage shows its time as it runs, and its own lines of the build log. When a stage fails, its log opens, with the message on top.

​
The smoke test

Before an image can become a version it has to prove it runs. Onecortex starts it with every configuration key you have set, each given a placeholder value rather than the real secret, and then:
  1. Waits up to 30 seconds for a health check. An agent that crashes on import, or takes longer to start, fails here with The agent did not start. and its own output.
  2. Sends one invocation, and waits up to 60 seconds. The prompt is __onecortex_healthcheck__, so you can recognise it in your logs.
  3. Checks the answer’s shape, not its content. It has to be a stream of valid events that ends in exactly one done. An agent that answers “invalid API key” because its model rejected the placeholder passes: it answered. An agent that raises fails.
An image that fails the smoke test never becomes a version, and there is no override.

​
A failed build

A build that fails produces no version, and the version that was live keeps serving. The build page shows:
  • the stage that failed, marked on the checklist;
  • the message, which says what went wrong and what to do;
  • where the cause is your own tooling or code, that tool’s output, unedited.
Every message and its fix is on Errors. Fix the cause, commit, and push, or click Deploy. A timeout at a stage says so: The deployment stopped at <stage> because that step ran out of time. Deploying again is usually enough.

​
Cancel a build

On a running build’s page, click Cancel, then Cancel build. The build stops where it is and produces no version. Nothing serving traffic changes.

​
How many at once

One agent builds one commit at a time. An organization runs at most three builds and rollbacks at once. A build started past either limit fails at Fetch source with This agent is already deploying. or Your organization is already running 3 deployments, the most it can run at once.

​
How long it takes

A first build is typically about two minutes, most of it installing dependencies. A build with large dependencies takes longer, and every stage shows its own time, so you can see where it goes.
Last modified on September 28, 2026