How deploys work

A deployment attempts to release a particular version of your application. The service stores configuration; deployment records describe attempts to turn that configuration and source into a running release. Saving a source setting and releasing that source are separate operations.

What starts a deployment​

A deployment can start during service creation, from a manual deploy action, from a Blueprint apply, or from a connected GitHub push when auto-deploy is enabled for the branch. Build filters and the selected source affect which pushes qualify. See GitHub integration.

In a Blueprint, autoDeployTrigger: commit enables commit-triggered deployment; off disables it. Bex currently rejects checksPass because it does not implement that CI-check gate. A public repository URL alone does not establish a webhook connection. An image tag changing in a registry does not itself submit a deployment.

Build cache​

Where caching is enabled, a deploy reuses the service's stored layers; see Build caching for the model. To force one deploy to rebuild every layer, clear the cache on that deploy only — the next deploy reuses the fresh cache normally. Accepted values are the string enum "clear" and "do_not_clear" (empty and omitted mean do_not_clear); with caching disabled on the instance, both values change nothing.

Clear from any surface:

bex deploys create srv-abc123 --clear-cache

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $BEX_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"clearCache":"clear"}' \
  "$BEX_API_URL/v1/services/$BEX_SERVICE_ID/deploys"

mutation {
  triggerDeploy(serviceId: "srv-abc123", clearCache: "clear") {
    id
    status
  }
}

In the dashboard, use the service's Clear build cache & deploy action. See deploys create for the CLI flags.

Follow a release​

1. Queued: the platform records the attempt and waits for build or runtime capacity and required infrastructure. A queued build is not yet executing.
2. Build: Git-backed services build the selected source. Docker builds use the repository's Dockerfile; native builds use the selected runtime and supplied commands. Prebuilt-image services skip source compilation.
3. Pre-deploy work: when configured for a supported workload, the pre-deploy command runs before the new release is promoted. A failed command prevents that release from proceeding.
4. Deploy or publish: long-running services roll out processes, static sites publish assets, and cron jobs update the executable and schedule.
5. Ready or failed: the deployment reports its result. Inspect its logs and status details rather than treating submission as success.

Open a deployment from the service's history to see its source revision, timeline, and available logs. Keep build failures separate from application startup failures: the corrective action depends on where the attempt stopped.

What readiness means​

An HTTP service without an explicit health path uses TCP probes. A process accepting TCP connections can still have application-level errors, so choose an HTTP health endpoint when you need a stronger readiness signal.

Deployment availability​

Ordinary long-running services use rolling updates. Readiness checks keep unready instances out of service traffic, but deployment success is not a universal zero-downtime guarantee: capacity, application behavior, shutdown, and storage all matter. For an application that finishes accepted HTTP work before exit, see HTTP shutdown drain.

A service with a persistent disk uses a Recreate deployment strategy so the old pod releases the volume before its replacement starts. Expect an interruption for that deployment shape. A first deployment has no previous healthy release to keep serving if it fails.

A failed build or pre-deploy command does not make the new release live. For rollout failures, inspect the active revision and ready instances rather than assuming the previous application is fully healthy. Use rollback when you need to restore a known release; database migrations and external side effects are separate from an image rollback.

Operational actions are distinct​

Restart, suspend, and resume operate an existing service without rebuilding its source. Use deploy to release a new revision. For cron jobs, a manual run executes the current job configuration rather than creating a new source build.

Troubleshoot in order​

Check the selected source and branch, then build logs, any pre-deploy command, runtime logs, and health-check results. For queued work, look for reported capacity or infrastructure waits. For a ready service with no reachable public URL, inspect routing and custom-domain configuration.

See Docker deploys, Logging, and Metrics for the next diagnostic step.

See pre-deploy commands for execution limits and migration guidance.

My change did not ship​

When the running code is not what you pushed, work in order:

1. Confirm the deployed commit. Open the deploy row and compare its commit with your push; a deploy triggered before the push landed — or pinned to an older commit — never contained your change.
2. Confirm the build ran. A deploy that reused a previous image (or a restart, which rebuilds nothing) cannot carry new code. Check the deploy's build logs in Logging.
3. Clear the cache and redeploy. If the build ran at the right commit but reused stale layers, trigger one deploy with the cache cleared (see Build cache above) and confirm the change lands.
4. Check env changes. If only configuration changed, confirm the new values are on the service and redeploy; a code-identical rebuild still re-runs env-dependent steps. See Environment variables & secrets.