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

# Builds

> How Horizon turns your repo into a deployable image.

Builds package hosted Python MCP and FastMCP servers into deployable artifacts.
A build belongs to one server and one source revision. Successful builds can be
served as live deployments or preview deployments.

For the hosted-server contract across source, builds, deployments, gateway
access, and runtime behavior, start with [Hosted servers](/servers/hosted).
For the full lifecycle, defaults, and failure modes, see
[Build system](/platform/build-system).

## Build contract

A build is an immutable attempt to turn one repository commit and one set of
server settings into one deployable artifact. After the build starts, changing a
branch, editing an environment variable, or updating server settings does not
change that build. Those changes apply to the next build that uses them.

| Property             | Contract                                                                                                     |
| -------------------- | ------------------------------------------------------------------------------------------------------------ |
| Source revision      | Resolved to an exact commit before build work begins.                                                        |
| Server configuration | Entrypoint, dependency file, build-relevant settings, and environment scope are captured at build start.     |
| Output               | A successful build produces a new artifact and manifest. A failed build does not modify the live deployment. |
| Mutability           | Build records and artifacts are historical. Rebuild instead of editing an existing build.                    |
| Promotion            | Build success makes an artifact eligible for deployment; it does not always change live traffic.             |

<Info>
  Debug build problems from the build record, not from the current branch tip.
  The current branch may have moved since the failed build started.
</Info>

## Build states

| State       | Meaning                                                                                                        |
| ----------- | -------------------------------------------------------------------------------------------------------------- |
| `queued`    | Horizon has accepted the build request and is waiting to start work.                                           |
| `building`  | Horizon is installing dependencies, packaging the server, inspecting the manifest, or publishing the artifact. |
| `succeeded` | The artifact is ready to deploy.                                                                               |
| `failed`    | The build did not produce a deployable artifact. Open build logs for the failing step.                         |
| `canceled`  | The build was stopped before completion.                                                                       |

## What starts a build

<CardGroup cols={2}>
  <Card title="Default branch push" icon="code-branch">
    A push to the configured default branch can create a production build.
  </Card>

  <Card title="Pull request" icon="code-pull-request">
    A pull request can create a preview build with preview-scoped environment
    variables.
  </Card>

  <Card title="Manual build" icon="play">
    A user with server edit access can start a build from the dashboard.
  </Card>

  <Card title="Configuration change" icon="sliders">
    Changes to build-relevant settings, such as the entrypoint or dependency
    file, take effect on the next build.
  </Card>
</CardGroup>

## What does not start a build

Not every server change produces a new artifact. Some changes affect gateway or
dashboard state without rebuilding Python code.

| Change                               | Usually requires a new build?                              | Why                                                                                  |
| ------------------------------------ | ---------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Source code change                   | Yes                                                        | The artifact must include the new code.                                              |
| Entrypoint or dependency file change | Yes                                                        | Horizon must package and inspect with the new build configuration.                   |
| Environment variable value change    | Yes, for hosted server runtime behavior                    | Existing artifacts keep the values they were built with.                             |
| Server access grant change           | No                                                         | Access metadata is evaluated by Horizon and can update without changing Python code. |
| Server display name or description   | No                                                         | Dashboard metadata does not affect the artifact.                                     |
| Capability policy change             | Redeploy may be required for hosted capability enforcement | The deployed endpoint must use the updated policy metadata.                          |

## Build inputs

| Input                 | Contract                                                                                              |
| --------------------- | ----------------------------------------------------------------------------------------------------- |
| Repository revision   | Horizon builds from the selected commit. Builds are immutable once started.                           |
| Entrypoint            | Defaults to `main.py` unless the server is configured with another entrypoint.                        |
| Dependencies          | Horizon installs dependencies from the configured dependency file or discovered Python project files. |
| Environment variables | Production builds use production variables. Preview builds use preview variables.                     |
| Access settings       | Authentication and authorization metadata are packaged with the deployment path used by the gateway.  |

## Source resolution

Horizon records the repository, branch context, and exact commit for every
hosted build. Branch names are useful for starting builds, previews, and
promotion workflows, but the artifact is tied to the commit that was resolved at
build start.

This matters when a pull request receives several pushes quickly. Preview builds
run concurrently, so an older build may finish after a newer one. Use the
deployment page to confirm which artifact is selected before assuming the latest
completed build is live.

## Build output

A successful build produces:

* A deployable artifact.
* A discovered MCP manifest for tools, resources, prompts, and templates.
* Build logs for audit and debugging.
* Metadata that Horizon uses for deployment, routing, and observability.

<Warning>
  Do not put required setup work behind a code path that only runs after a tool
  call. Horizon inspects the server during the build, so import-time and startup
  failures can prevent deployment.
</Warning>

## Concurrency and ordering

Default-branch deploys to the same server run one at a time. When you push
several commits in quick succession, their builds run in parallel but deploy
serially, so the newest commit is the last one applied and owns live traffic.
Preview builds still run concurrently across branches.

| Scenario                                                         | Expected behavior                                                                              |
| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Several commits pushed to the default branch in quick succession | Each commit builds, and the deploys apply in order. The newest commit ends up live.            |
| Two preview builds run for different branches                    | Previews deploy concurrently; each branch serves its own artifact.                             |
| A default-branch build succeeds while a preview build fails      | The production artifact can still be healthy; preview failure is scoped to its branch context. |
| A build fails after a previous build succeeded                   | The previous successful artifact remains available for deployment or rollback.                 |

## Manifest inspection

Build inspection loads the server entrypoint and records the MCP capabilities
Horizon can see. The dashboard, ChatMCP, remix composition, and capability
policies depend on that manifest. Playground lists live capabilities from the
selected target instead.

If a capability is missing after a successful build, check whether the server
registers the tool, resource, prompt, or template during import or startup.
Conditional registration can make local behavior differ from build inspection,
especially when it depends on environment variables.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Dependency installation fails">
    Check the dependency file path, Python version requirements, private package
    credentials, and any build-time environment variables.
  </Accordion>

  <Accordion title="The entrypoint cannot be loaded">
    Confirm the configured file exists in the repository revision and can be
    imported without running interactive code.
  </Accordion>

  <Accordion title="The manifest is empty or incomplete">
    Make sure tools, resources, and prompts are registered before the server is
    inspected. Build logs usually show whether inspection succeeded.
  </Accordion>

  <Accordion title="A new environment variable is missing">
    Start a new build after saving the variable. Existing artifacts keep the
    environment available when they were built.
  </Accordion>

  <Accordion title="A successful build did not change production traffic">
    Confirm whether the build was for a preview deployment, whether automatic
    promotion is enabled, and which artifact the live deployment currently
    selects.
  </Accordion>

  <Accordion title="A tool disappeared after a build">
    Compare the manifest on the previous successful build with the new build.
    Then check registration code and environment-dependent imports.
  </Accordion>
</AccordionGroup>

## Related docs

<CardGroup cols={2}>
  <Card title="Hosted servers" icon="server" href="/servers/hosted">
    Start with the hosted-server contract across source, deployments, access,
    runtime, and observability.
  </Card>

  <Card title="Deployments" icon="cloud-arrow-up" href="/deployments">
    Serve successful builds as live or preview deployments.
  </Card>

  <Card title="Environment variables" icon="lock" href="/environment-variables">
    Manage production and preview environment variables.
  </Card>

  <Card title="Compute model" icon="server" href="/platform/compute-model">
    Understand how artifacts run after deployment.
  </Card>
</CardGroup>