Application Deployments

Deployments can target all services in an app environment or only selected services.

Within a deployment, Wodby orders services using both explicit stack depends rules and the current links between app services. If two linked services are deployed together, the linked target service is deployed first.

Deployments use automatic rollback by default. Rollback is best-effort and applies to the app service release that fails.

Every deployment is associated with a specific stack revision of the app environment.

When a deployment starts, Wodby checks app-service configuration and writes relevant issues to the deployment task as warnings instead of rejecting the deployment. A full deployment reports issues from all enabled services. A partial deployment reports issues for its selected services, together with any environment-wide issues. Review these warnings: the deployment continues, but an affected workload may not operate correctly until its required build source, external database, integration, linked setting, or other required setting is configured.

Deployments are usually triggered in the following ways:

• automatic first deployment after app creation when services can deploy immediately or build with Wodby CI
• deployment of builds requested from CI
• automated partial deployments for service-level maintenance
• manual deployment from the UI

New deployment

A new deployment can be started manually from Apps > [App] > [Environment] > CI/CD > Deploys > New Deployment.

In that flow you can:

• choose which services to deploy
• force deployment even when manifests have not changed
• disable post-deployment scripts for services that provide them
• use Skip rollback on failure when you want to inspect the failed state instead of restoring the previous deployment
• choose from available successful builds for services with build sources, including eligible older builds
• choose New build only when the app service's CI provider and build source support dashboard-triggered builds

If New build is unavailable, the build selector explains whether the service needs a linked repository and ref, a previously recorded GitHub Actions or CircleCI workflow from the selected ref, or whether it uses external-only Custom CI. A compatible previous successful build remains selectable even when the dashboard cannot start a new one.

When you select New build for multiple source owners, Wodby creates one awaiting deployment and starts the supported builds together. That deployment waits for exactly the selected owners. Selecting only one source owner does not wait for other buildable services in the app; a full new-build deployment includes every build-source owner and waits for all of them.

When a selected source owner uses New build, selected linked image targets and derivatives that consume its output follow that same new build. Wodby does not keep an older image selection for one of those consumers inside the same deployment. A previous successful build selected for another service is treated only as a reusable image: it does not satisfy a selected New build, keep the deployment waiting, or make that deployment depend on another CI run.

If you deploy only a subset of services, Wodby applies that ordering only inside the selected set. Repository post-deployment scripts run only when the app service that owns the corresponding build is included in the selected deployment. Reusing that build for another selected service does not make the build owner's scripts applicable.

Roll back to previous builds and deployments

You can manually move app services back to versions produced by earlier builds in three places:

• select an older build for one or more services in New Deployment
• open a build that was deployed before and is older than the currently deployed build, then select Roll back to this build; an older build that was never deployed instead uses Deploy this older build
• open an earlier deployment and select Roll back to this deployment when it restores older, previously deployed builds; otherwise the action remains Redeploy

The build selector lists only eligible images. It marks an image that is in use as Currently deployed and shows an Older stack revision warning on selectable images built for an earlier stack revision. A completed, non-voided image from the current stack revision can be selected even if it has never been deployed before. An image from an older stack revision is selectable only when that exact app-service image completed a deployment previously. Missing, voided, incomplete, and ineligible cross-revision images remain visible in build history but are omitted from the selector. The selector groups eligible previous choices under Older builds.

A build rollback uses the current stack

Rolling back to a previous build—or deploying an older build that was never deployed—does not downgrade the app environment's stack. Wodby renders the deployment with the current stack revision, configuration, secrets, volumes, and linked services. It also does not restore databases or other persistent data.

An older image can be incompatible with the current database schema, stored data, environment variables, service versions, or stack configuration. This risk exists even when the image was built for the current stack revision; using an image from another revision adds stack-compatibility risk.

Before starting a build rollback or older-build deployment, the dashboard lists the affected services, build numbers, and build stack revisions and requires an acknowledgment checkbox. Post-deployment scripts are turned off by default for older builds because they can run migrations or other data-changing operations. In New Deployment, you can explicitly turn a service's scripts back on after reviewing them. The build and deployment detail shortcuts keep those scripts off; use New Deployment if you intentionally need to run them.

Deployment history keeps the original build transition visible after the selected build becomes current:

• Build rollback means the deployment replaced newer builds entirely with older builds that had been deployed successfully before.
• Includes build rollback means only some selected services rolled back to previously deployed builds.
• Older build means an older selected build had never been deployed before, so it is not labeled as a rollback.
• Older stack revision means at least one selected build was created for an earlier stack revision.

Deployment details show the tags per app service together with the previous and selected build numbers, for example Build #7 → #5. These build-selection tags describe the intentional version change; they are separate from automatic rollback on rollout failure.

Automatic rollback on rollout failure remains enabled unless you select Skip rollback on failure. That rollback can restore the previous Kubernetes release after a rollout failure, but it still does not restore application data or downgrade the stack.

The generic task Repeat action remains limited to the latest deployment. To restore an earlier deployment, open its deployment details and use its Roll back to this deployment or Redeploy action, which applies the older-build eligibility checks and confirmation.

Post-deployment scripts

CI scripts defined in .wodby/post-deployment.yml run in a separate task after the application rollout succeeds. The deployment and post-deployment task therefore have separate outcomes:

• the deployment is completed when the selected app services roll out successfully
• the post-deployment status separately shows whether scripts are pending, running, completed, failed, canceled, skipped, not run, or not applicable

A later rollout waits until the deployment and its post-deployment scripts finish. If the rollout fails or is canceled, the scripts do not run and their status is not run.

If a post-deployment script fails, the completed deployment and app environment remain successful. Wodby shows a post-deployment warning with separate task logs and does not roll back the deployed app services. You can retry the post-deployment task without redeploying the application while that deployment remains active for the app environment. After another deployment becomes active, the older deployment's post-deployment task can no longer be retried.

Wodby CLI deployment commands that stream logs or wait for completion follow both tasks. If the rollout succeeds but the post-deployment task fails, the CLI returns a non-zero exit code with a message that distinguishes the script failure from deployment failure. wodby ci deploy remains asynchronous: it queues the deployment and does not wait for either task to finish.

Rollout health checks and failure logs

Applying the Kubernetes resources does not finish a deployment. Wodby waits for the selected workloads to complete their rollout: the requested replicas must be running the updated workload and pass its readiness checks. Deployments and DaemonSets must also report the replicas as available. A container can be running while its workload is still waiting for readiness or a configured minimum-ready interval.

For workloads monitored by Wodby's Kubernetes watcher, failure handling depends on the condition:

• CrashLoopBackOff: Wodby allows a one-minute recovery window from the first time it observes this state for a container in a pod. This applies to both application and init containers. Restarts of that container do not reset the window; a replacement pod gets its own window. If Wodby observes the container in CrashLoopBackOff after the window expires, it fails the rollout. The first warning therefore does not immediately fail the deployment.
• Image or container startup errors: states such as ErrImagePull, ImagePullBackOff, InvalidImageName, and CreateContainerConfigError fail the rollout when detected, without the crash-loop recovery window.
• No rollout progress: a Deployment reporting ProgressDeadlineExceeded fails the rollout. Increasing its progress deadline does not extend the separate crash-loop recovery window.
• Pods cannot be scheduled: Wodby applies a separate scheduling limit of seven minutes, or three minutes on serverless clusters, measured from when it starts inspecting each pod. Another deployment limit can end the wait sooner.

The one-minute window is not a total deployment timeout or a guarantee that the task will finish exactly one minute after the first warning. Pod inspection, failure diagnostics, and automatic rollback can add time. See Deployment wait times for how rollout settings affect other waits.

When a watched workload fails, Wodby attempts to add pod conditions, container states, warning events, and the previous container attempt's logs to the task log. Look for Previous logs when the current container is waiting in CrashLoopBackOff: the startup error may belong to its previous attempt. Diagnostic collection is bounded, so the task log may contain only a tail of the available output.

Deployment rollback

When an app service upgrade is applied and its workloads fail health checks, Wodby tries to roll that service release back to the latest previous successful release. The deployment still fails, but a successful rollback restores that service to the previous release. The deployment task stays active while rollback runs and waits for the restored workloads to become ready. The final failure message can therefore appear after the rollback logs, even though the rollout failure was detected earlier.

Rollback is per app service release. It does not undo other app services that were already deployed successfully during the same deployment.

Rollback is not always possible. Wodby does not attempt rollback when:

• Skip rollback on failure is selected or --skip-rollback is used
• the service is being installed for the first time
• the service has no previous successful release
• the failure happens before the Helm upgrade is applied
• the deployment is canceled, interrupted, or times out while waiting for workloads

Wodby also skips rollback when the current and previous release would apply the same Kubernetes resources and there are no rollback hooks to run. Reapplying that release would not correct the unhealthy workload; the task log explains why rollback was skipped.

Failures in .wodby/post-deployment.yml happen after a successful rollout and never trigger deployment rollback.

If rollback is not attempted, the failed release state remains in the cluster. If rollback is attempted but fails, the deployment remains failed and the task logs include the rollback error.

Deployment history and deployment details show rollback status when Wodby rolled back successfully or when rollback failed. Deployments without a rollback do not show a rollback status.

Failed deployment notifications include whether Wodby rolled back, did not roll back, or attempted rollback and failed.

App service status after deployment

An app service's status reflects the outcome of its own rollout, not just the overall deployment:

• A successful rollout sets the app service to ok, or disabled when the service is disabled.
• If an earlier check or dependency failure prevents the service rollout from starting, Wodby keeps the service's previous status. Its deployment is canceled and the service remains marked for redeploy.
• If the service rollout starts and then fails or is canceled, the app service becomes errored.
• If that failed rollout is successfully rolled back, Wodby restores the service's previous healthy ok or disabled status. The deployment still fails and the service remains marked for redeploy.

A successful build does not change an app service's deployment status. After a rollout error, deploy the service again to clear the error, unless an automatic rollback already restored its previous healthy status.

Force deployment

Use force deployment when you need Wodby to redeploy a selected app service even though the rendered Kubernetes manifests have not changed.

For non-external services, force deployment restarts the service pods with the selected chart values and image references, even when those values have not changed.

Force deployment does not create a new build or change which image is deployed. For services with build sources, choose the build you want to deploy in the same way as a regular manual deployment.

Force deployment requires the service to define resolvable workload selectors. If Wodby cannot resolve the workload selectors for a forced upgrade, the deployment is stopped before the Helm release is changed. External services do not have Kubernetes workloads to restart.

Deployment readiness and queueing

Awaiting and Queued describe different stages of a deployment:

• Awaiting means Wodby cannot create the deployment task yet. For example, one or more selected new builds have not supplied deployable images, or the target cluster is undergoing an infrastructure upgrade.
• Queued means the deployment has everything it needs and its task is waiting for execution capacity or for a conflicting deployment or post-deployment operation to finish.

Wodby keeps app-wide deployment operations serialized, but eligible partial deployments can roll out concurrently when they affect independent resources. If several deployments are requested, each keeps its own service and build selections and joins that environment's task queue when it becomes ready. Builds can finish in a different order from the requests, so deployments are queued in readiness order, not necessarily deployment-number order.

Parallel partial deployments

On Wodby infrastructure version 4.0.0 or newer, an app environment with a working deployment and completed routing migration can run up to two independent partial deployments at a time. Deployments that share builds, dependencies, volumes, or certificates wait for one another. Wodby also queues deployments when it cannot establish that they are independent.

Parallel deployments remain in progress until their shared routing and DNS update finishes. An independent deployment can succeed even if another fails or is canceled. If the shared routing or DNS update fails, all deployments waiting for that update fail. Check the task logs before retrying.

First and full deployments, migrations, imports, repository post-deployment scripts, and deployments of external, storage, infrastructure, or operator services run one at a time. Environments on older routing infrastructure or with an unfinished routing migration also run deployments one at a time.

A deployment's repository post-deployment scripts finish before a later rollout starts. If the deployment fails or is canceled, its scripts do not run.

Starting another deployment does not replace a pending request. Cancel unwanted deployments or their tasks explicitly.

First deployment

Initial deployment depends on how the app's services are built:

Build sources	What happens after app creation
No services need a build	Wodby starts a full deployment immediately.
All builds use Wodby CI	Wodby starts the builds and deploys when they are ready.
All builds use third-party CI	The app remains awaiting. Run your external pipeline and call wodby ci deploy to deploy its services with pushed images.
Wodby CI and third-party CI	Wodby starts its CI builds and deploys their services without waiting for external pipelines. Run those pipelines to deploy the remaining services.

During initial setup, build-backed deployments also include all enabled services without build sources while any of those services has never deployed successfully. After initial setup, a partial deployment includes an unrelated service without a build source only when it is marked needs redeploy and is not already included in another active deployment. An unhealthy status alone does not add a service to a partial deployment.

Optional build image targets without their own source can use the image produced by their linked owner or their configured service image when that build does not provide one.

A partial deployment can complete successfully while the app environment remains awaiting. The environment becomes ok only after every enabled service that requires a Wodby-managed runtime has a usable deployment. Services omitted from the first build group can be deployed by their own CI handoff or a later manual deployment.

Deferred initial deployment

The API can create an app environment with its initial deployment deferred. This lets automation finish configuring the environment and its services before any application workloads are started. The environment remains awaiting until you explicitly start its first build or deployment.

While the initial deployment is deferred, enabling a service saves the enabled state and marks the app environment as needs redeploy; it does not start an automatic partial deployment. This remains true until a deployment establishes the app's runtime and active route backends. Start a deployment that includes the app's required services after configuration is complete.

Automated redeployments

Some platform operations automatically redeploy only the affected app services. Examples include SSH authorized-key refreshes and completing an import.

When an affected service uses a build image, Wodby prefers its last successfully deployed build. That known-good image can be reused after a stack upgrade even though it was built for the previous stack revision. The task log warns when this happens and shows the selected build and both revision numbers.

An automatic stack upgrade runs repository-defined .wodby/post-deployment.yml scripts for a build-source service only when the upgrade rebuilds that service. If the service needs only a runtime redeployment, Wodby reuses the existing build and records its post-deployment scripts as skipped. This prevents an unchanged build from automatically repeating migrations or other data-changing jobs. Service-manifest post_deploy actions are separate lifecycle hooks and are not disabled by this repository-script skip.

Automatic selection does not search arbitrary build history. Once a newer build is successfully deployed, the previous build is no longer considered the last known-good image and is not selected automatically across stack revisions. Any other automatically selected build must be successful, non-voided, and built for the app environment's current stack revision.

Wodby does not silently replace a missing reusable build with the service's default image. If neither the last successfully deployed build nor a compatible current-revision build is available, the automated operation stops before creating the deployment and its task log asks you to run and successfully deploy a new build.

Routing deployments

On clusters with Wodby infrastructure version 4.0.0 or newer, HTTP routing has a deployment lifecycle separate from app-service workloads. Wodby can apply these changes without rebuilding images or redeploying app services:

• adding, editing, retargeting, disabling, or deleting a route
• changing app-level or route-specific route settings
• changing HTTP authentication
• issuing or renewing a route certificate

Routing deployments update the complete routing configuration for one app environment. Repeated changes made while an update is running are combined and followed by another routing update when necessary.

The app environment shows Updating routing while its desired routing configuration has not yet been applied. During the one-time upgrade from service-owned routing, it shows Migrating routing. These states are separate from needs rebuild and needs redeploy, which continue to describe app builds and service workloads.

Automatic routing deployments, including deployments after certificate renewal, create background tasks for logs and failure tracking. You do not need to start an app-service deployment after a successful routing-only change, unless the change adds or removes a hostname or changes the Main domain. Then the app environment is marked needs redeploy so your app receives its new hostnames. See Domains.

After a partial workload deployment, Wodby applies routing for app services that currently have a successful deployed runtime. Routes to services that have not deployed successfully are omitted instead of being applied to missing Kubernetes Services; redirects remain available because they do not require a service backend. The task log identifies omitted backends, the app environment returns to awaiting, and it remains marked needs redeploy. A later workload deployment reevaluates every service and adds each route after its backend becomes available.

Clusters older than infrastructure version 4.0.0 continue to apply route, auth, and certificate changes through the affected app-service releases. Those apps may still show needs redeploy until the cluster infrastructure is upgraded.

Build deployment

Deployments from CI are triggered with wodby ci deploy.

Each build deployment creates a new deployment record associated with the selected build. One build can contain image outputs for multiple app services. CI-triggered deployments can also skip post-deployment scripts for the built services when needed.

A CI build started outside an existing dashboard build group deploys its own pushed service images without waiting for unrelated build-source owners. On an app that has not established its runtime yet, Wodby also includes the enabled services without build sources required for that initial runtime. Other build owners remain independent and deploy when their own builds report back.

Regular app builds can continue while the target cluster is undergoing an infrastructure upgrade. If all required builds become ready during the upgrade, the deployment remains awaiting without a deployment task. Wodby starts it automatically after the cluster returns to ok; you do not need to trigger the deployment again. If the infrastructure upgrade fails, the deployment continues waiting until the cluster recovers to ok.

Needs redeploy

When app-service configuration changes, the app environment can be marked as needs redeploy.

This means configuration has changed, but those changes have not yet been applied to the running deployment.

Auto redeployment

Some service-level redeployments happen automatically. Routing-only changes on infrastructure version 4.0.0 or newer use a routing deployment instead and do not restart app-service workloads.