> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onecortex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Builds

> What happens in each of the nine build stages, what the smoke test checks, what fails where, and how to read and cancel a build.

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.

```mermaid theme={null}
flowchart LR
  a["Fetch source"] --> b["Validate<br/>agent.yml"] --> c["Generate<br/>build files"] --> d["Prepare<br/>infrastructure"] --> e["Build image"] --> f["Smoke test"] --> g["Release"] --> h["Go live"] --> i["Finalize"]
  f -. fails .-> x["No version.<br/>Live version keeps serving."]
```

## 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](/deploy/auto-deploy).
* A configuration change, with automatic deploys on: **triggered by a configuration change**.

## The stages

| Stage | What happens | What fails here |
| - | - | - |
| **Fetch source** | The commit is downloaded from GitHub, read only, and the agent folder is taken from it. | An empty commit or folder; more than 50,000 files or 500 MB; another build already running |
| **Validate** `agent.yml` | The file is checked, with the same checks as the wizard, against the files in the commit. | Every [`agent.yml` error](/production/errors#agent-yml-errors) |
| **Generate build files** | Onecortex writes a Dockerfile and adds the shim beside your code, in `_onecortex/`. Your files are not changed. | Rarely: deploy again |
| **Prepare infrastructure** | Your agent's runtime, logs and permissions are set up, once, and checked on every build. | A location that is not offered |
| **Build image** | The image is built for 64 bit ARM Linux, and your dependencies installed from your lockfile. | A dependency that will not install, one with no ARM build, an image over 2048 MB |
| **Smoke test** | The image is started and called once, as described below. | An agent that does not start, raises, or answers in the wrong shape |
| **Release** | The tested image becomes the agent's new version, with your configuration injected, and starts. | A version that passed the smoke test but did not start |
| **Go live** | The endpoint answers from the new version. | Rarely: deploy again |
| **Finalize** | The build is recorded, and versions beyond the last ten are pruned. | |

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](/production/errors#build-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.