> ## 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.

# Deployments

> Stable MCP URLs, preview deployments, promotion, redeploy, and rollback.

Deployments decide which built server artifact receives MCP traffic. A build
turns one repository commit into an immutable artifact. A deployment gives that
artifact a Horizon URL, records the branch and commit it came from, and can make
it the live production version for the server.

In practice, clients call a Horizon MCP URL, usually ending in `/mcp`, and
Horizon routes that request to the artifact selected by the relevant deployment.
Production traffic uses the stable server URL. Pull requests and non-default
branches can use preview deployment URLs so you can test changes before they
become production.

For the build step before deployment, see [Build system](/platform/build-system).
For request routing after deployment, see [Gateway](/gateway).

<Info>
  Open a server in Horizon, then select **Deployments** in the server sidebar.
  The page shows the stable MCP URL, current status, recent build activity, and
  a history of builds and deployments for that server.
</Info>

## Deployment model

<CardGroup cols={2}>
  <Card title="Production URL" icon="route">
    The server's stable MCP URL always points clients at the artifact currently
    selected for production.
  </Card>

  <Card title="Preview URL" icon="code-pull-request">
    A pull request or branch build can expose an isolated preview URL for
    testing that branch's artifact.
  </Card>

  <Card title="Build record" icon="code-branch">
    Every deployment is tied to the build, commit SHA, branch, and pull request
    metadata that produced it.
  </Card>

  <Card title="Promotion" icon="cloud-arrow-up">
    Promotion changes which default-branch deployment receives production
    traffic without asking clients to change URLs.
  </Card>
</CardGroup>

## What starts a deployment

A deployment starts after Horizon has a build request and a deployment target.
The target determines whether the result is production-ready or preview-only.

<Steps>
  <Step title="Default branch push">
    A push to the server's default branch creates a production build. If
    auto-promotion is enabled and the build succeeds, Horizon selects the new
    deployment for the stable production URL.
  </Step>

  <Step title="Pull request update">
    A pull request toward the default branch creates a preview build and preview
    deployment URL. The preview uses preview-scoped environment variables and
    can be tested without changing production traffic.
  </Step>

  <Step title="Manual redeploy">
    From a build row, you can start a new build from that row's commit. Use
    this when current server settings, environment variables, access policy, or
    deployment metadata need to be applied to that commit again.
  </Step>

  <Step title="Manual promotion">
    If a successful default-branch deployment is not live, use **Promote to
    live** to select it for production. Promotion keeps the same stable server
    URL and changes the artifact behind it.
  </Step>
</Steps>

<Note>
  A successful build does not always mean production traffic changed. Preview
  builds stay preview. Default-branch builds can also remain ready-but-not-live
  when auto-promotion is disabled or when a newer deployment has already been
  selected.
</Note>

## Production and preview URLs

Production clients should use the stable server URL shown at the top of the
Deployments page. That URL is based on the server name and remains the client
configuration target through future promotions and rollbacks.

Preview deployments use branch-scoped URLs. Horizon derives a deployment slug
from the server name and branch name, lowercases it, replaces unsupported
characters with hyphens, and truncates long values to fit URL and runtime naming
limits. Pushes to the same preview branch reuse the branch deployment slug, so
the preview URL can stay stable while its selected artifact changes.

| URL type                         | Typical use                                       | What changes                                                                        |
| -------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Stable production URL            | Client, automation, and production traffic        | The selected production artifact changes on promotion or rollback.                  |
| Preview deployment URL           | Pull request review and branch testing            | The preview artifact changes when that branch receives a new successful deployment. |
| [Custom domain](/custom-domains) | Client-facing hostname owned by your organization | It routes to the same Horizon-served endpoint as the default URL.                   |

<Warning>
  Do not treat a deployment URL as an access control boundary. Use Horizon
  authentication, server access, and capability policies for access control.
</Warning>

## Status labels

The Deployments page combines build and deployment state into labels that are
meant to answer one question quickly: what is this row doing for traffic?

| Label        | Meaning                                                                                                                            |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `Production` | This successful default-branch deployment is selected for the stable production URL.                                               |
| `Preview`    | This successful non-default branch or pull request deployment has a preview URL and is not production.                             |
| `Ready`      | This successful default-branch deployment can be promoted, but it is not currently production.                                     |
| `Building`   | The build is queued or running. The selected production artifact has not changed yet.                                              |
| `Failed`     | The build did not produce a deployable artifact. Existing live traffic remains on the previously selected artifact, if one exists. |

The page also shows a top-level server status:

* `Live` means the server has a live production deployment.
* `Building` means at least one build is queued or running.
* `Failed` means the latest build failed.
* `No deployments` means Horizon has not created a deployment for the server yet.

## Auto-promotion

Hosted servers have an **Auto-promote Deployments** setting. When it is enabled,
successful default-branch deployments become production automatically. Horizon
demotes the previous production deployment for the same server and points the
stable URL at the new successful artifact.

When auto-promotion is disabled, successful default-branch builds appear as
`Ready`. Review the commit, build logs, server logs, and preview behavior, then
promote the deployment manually when it should receive production traffic.

<Tip>
  Disable auto-promotion when you want a human approval step between a
  successful default-branch build and production traffic.
</Tip>

## Repeat deployments and rollback

Starting another deployment from a commit and rolling back production create
different operational outcomes.

<AccordionGroup>
  <Accordion title="Create another deployment from a commit">
    Use a build row's action menu to create a new build and deployment from
    that row's commit. The new build captures current server settings that
    affect deployment, such as entrypoint, dependency file, environment values,
    authentication mode, and capability policy metadata.
  </Accordion>

  <Accordion title="Roll back production">
    To roll back, find an earlier successful default-branch deployment and
    promote it to live. The stable production URL stays the same, but Horizon
    selects the earlier artifact behind it.
  </Accordion>

  <Accordion title="Keep preview separate">
    Promoting to production is only available for successful default-branch
    deployments. Preview deployments are for branch testing and do not become
    production directly.
  </Accordion>
</AccordionGroup>

After redeploying or promoting, reconnect MCP clients that cache manifests or
capability lists. Some clients do not refresh tools, resources, or prompts until
they reconnect or list capabilities again.

## What changes when

Deployment behavior depends on which boundary owns the change.

| Change                                | What to do                                             | When clients see it                                                                 |
| ------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| Source code changes                   | Create a new build from the changed commit.            | After the resulting deployment is selected for the URL the client uses.             |
| Environment variables change          | Create a new build for the relevant environment.       | After a new deployment uses the updated values.                                     |
| Entrypoint or dependency file changes | Create a new build or wait for the next build trigger. | After a successful deployment built with the new settings is selected.              |
| Authentication mode changes           | Create a new deployment for the hosted server.         | After a deployment uses the updated setting.                                        |
| Server grants or default role changes | Save the access change.                                | After Horizon updates live access metadata. A code build is not required.           |
| Capability policy changes             | Save the policy, then redeploy.                        | After the deployed endpoint uses the updated policy metadata.                       |
| Custom domain changes                 | Complete domain setup or migration.                    | After DNS, activation, and client configuration all point to the intended endpoint. |

## Debug deployment behavior

Start from the row that matches the commit and URL you are testing. The
Deployments page gives each row actions for build logs, server logs, copying the
deployment URL, redeploying, and promoting when promotion is available.

<AccordionGroup>
  <Accordion title="A build succeeded but production did not change">
    Check whether the row is labeled `Preview`, `Ready`, or `Production`.
    Preview deployments do not change production. Ready deployments need manual
    promotion when auto-promotion is disabled.
  </Accordion>

  <Accordion title="A client still sees old tools">
    Confirm the production row has the expected commit and manifest. Then
    reconnect the client or list capabilities again because some clients cache
    server metadata.
  </Accordion>

  <Accordion title="A preview URL shows unexpected behavior">
    Confirm the branch and commit SHA on the deployment row. Branch names start
    builds, but each build is tied to the exact commit Horizon resolved when the
    build started.
  </Accordion>

  <Accordion title="Promotion fails">
    Confirm the deployment belongs to the default branch, succeeded, and is not
    already production. If the row should be promotable but promotion fails,
    open build logs and server logs, then retry from the deployments table.
  </Accordion>

  <Accordion title="A deployment URL returns an access error">
    The request reached Horizon but did not pass the server's access settings.
    Check [Authentication](/platform/authentication),
    [Authorization](/platform/authorization), server access, API keys, and
    request logs.
  </Accordion>

  <Accordion title="A request reaches the server and then fails">
    Gateway routing succeeded. Check your server logs for stdout, stderr,
    startup failures, handler errors, or upstream failures from the running
    Python server.
  </Accordion>
</AccordionGroup>

## Operational checklist

Before sharing or promoting a deployment, confirm:

* The row has the expected branch, pull request, commit SHA, and status.
* The stable production URL or preview URL is the URL you are testing.
* Build logs show a successful package and inspection step.
* Server logs do not show startup or request-time failures for representative
  calls.
* Environment variables are scoped correctly for production or preview.
* Authentication mode, server access, and capability policy match the intended
  audience.
* Clients have reconnected or refreshed capabilities after a manifest-changing
  deployment.

## Related docs

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

  <Card title="Build system" icon="hammer" href="/platform/build-system">
    Learn how Horizon produces deployable artifacts from Python MCP and FastMCP
    source code.
  </Card>

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

  <Card title="Custom domains" icon="globe" href="/custom-domains">
    Serve the production deployment from a subdomain you control.
  </Card>
</CardGroup>