Deployments

For the broader concept of projects and deployments, see Projects and Deployments.

How a deployment is triggered #

Two ways:

• Initial — creating a Git-backed project provisions it on the selected server and starts its first deployment.
• Automatic — when you create a project in Depfloy, a webhook is registered with your Git provider. Tick Enable Auto Deploy on the project (during create, or later under Settings) and every push to the configured branch triggers a deployment.
• Manual — click Deploy on the project’s Summary view, or use the API.

Open the project from the setup guide to follow the first deployment. If setup or the deployment fails, the guide returns to that project so you can read the failed step, correct the configuration, and retry.

Deployment lifecycle #

A deployment moves through these states:

1. Created — the request was recorded.
2. Queued — Depfloy is waiting for the server’s deployment queue to free up, or for an in-flight deployment on this project to finish.
3. Deploying — Depfloy is running the build (install dependencies, build assets, switch the active release, restart services).
4. Success, Failed or Cancelled — the final state.

For release-based deployments, a build failure before switchover leaves the previous release selected. Shared configuration, database changes and server resource pressure can still affect the running application. Cancellation has its own timing constraints; see Cancelling a deployment.

Multiple pushes to the same project #

If commits arrive faster than Depfloy can deploy them, the currently running deployment keeps going and the newer commits sit in a queue behind it. The project header shows Deploying with a small +N queued badge so you know more work is coming. When the active deployment finishes, the next queued one starts automatically.

This is a recent change. Previously, a second push could appear to bump the running deployment off the project view, and people tended to click Reset Deployment Status to “clear” things — which actually caused the running deployment to lose its tracking and leave the project in an inconsistent state.

Resetting the deployment state #

If a project ever does get stuck in Deploying for far longer than it should, the project actions menu (three-dot in the header) has a Reset Deployment Status action. Use it sparingly.

When you click it, Depfloy first checks whether a deployment is genuinely still running:

• If not, the state is cleared and you can deploy again.
• If yes, you’ll see a strong warning: resetting will delete the active deployment record and may leave the project in an inconsistent state. Only confirm if you understand the consequences.

In most cases, Rerun on the Deployments page is the safer recovery action.

Inspecting a failed deployment #

When the most recent deployment failed, the red Failed badge in the project header is clickable. Clicking it opens a side sheet with the full deployment log, ANSI-coloured, so you can scroll through what went wrong without leaving the Console.

Invalid environment file #

Before the build starts, Depfloy checks that your project’s environment variables can be parsed. The usual culprit is a value containing spaces that isn’t quoted — APP_NAME=Labs Office, for example.

When that happens the deployment stops right away, at the top of the log, with a message that names the problem:

Environment file is invalid: ...
Fix the environment variables (e.g. wrap values containing spaces in quotes) and redeploy.

Quote the value on the Environments tab (APP_NAME="Labs Office") and deploy again. Previously a mistake like this only surfaced much deeper into the build, as a cryptic dependency-installation error that gave no hint about the real cause.

The global Deployments page #

The Deployments tab in the top bar lists every deployment across all servers in your organization, with filters and bulk actions.

Filters and search #

• Search — across description, branch, commit SHA prefix, commit message, and project name
• Project and Server — filter to a single project or server
• Status — multi-select chip group: Queued / Deploying / Success / Failed / Created
• Branch — filter by branch name (case-insensitive equality)
• Date range — Last 24 hours (default), 7 days, 30 days, All time

The filter combination is reflected in the URL so you can share or bookmark a view. Clear filters resets everything.

Stats summary #

The top of the page shows a quick count for the selected date range: X deploys · Y succeeded · Z failed · N in progress. Realtime updates keep this current as deployments finish.

Per-row actions #

Click the kebab … on a deployment row:

• View Log — always available; opens the full deployment log dialog.
• Cancel deployment — only available while a deployment is queued or building. Requires confirmation. See below.
• Rerun — only available for failed deployments. Queues a new deployment using the same commit. Requires confirmation.
• Rollback — only available for successful deployments that are not the currently active one. See below.

Recent deployments on the project Summary #

A project’s Summary tab lists its last five deployments — status, commit message, how long it took, when it ran, and whether it came from a push or was started by hand — so the two questions you usually have there (“what shipped before this?” and “put yesterday’s build back”) do not mean leaving the tab.

The list is live: while a deployment is running its row reads Deploying and moves to its final state without a reload. A deployment you have cancelled reads Cancelling rather than Deploying, so you can see the cancellation landed and do not press it twice.

Each row’s ⋯ menu has two actions:

• View logs — that deployment’s build log.
• Roll back to this deployment — puts that commit back in service, after a confirmation.

Roll back is only offered on a deployment that succeeded, has a commit, and is not the one currently serving; it is unavailable entirely while another deployment is running, since two cannot run at once. It needs the deployment:create permission — a member without it sees only View logs.

The Rollback dialog in the header’s ⋯ menu, which chooses from the last 20 successful deployments, is unchanged.

Cancelling a deployment #

Cancel is the tool for a deployment you did not mean to start — the wrong branch, a commit you spotted a mistake in, or simply a second thought. It is available while the deployment is Queued or Deploying, from the row menu on the Deployments page and from the project card in the Console.

A queued deployment stops immediately. One that is already building stops within seconds: Depfloy ends the build, kills the install or compile step still running on the server, and deletes the half-finished release.

Your site is not affected. Depfloy builds every deployment in a release of its own and switches your site over as the very last step, so a deployment cancelled before that switch never served a single visitor. The release that was live stays live, on the same code, with no restart.

Cancel stops being offered once a deployment leaves Queued and Deploying. Which refusal you get depends on where it got to: a deployment that has finished is refused with “this deployment has already finished”, and one that is still building but has already switched your site over — a window of seconds — is refused with “already serving traffic” and pointed at rollback. Rollback is the action that returns a site to its previous release in either case.

A cancelled deployment is recorded with its own Cancelled status rather than as a failure. It does not change the project’s own status either: a project whose latest deployment was cancelled still shows as deployed, because it is.

In the stats summary it counts towards the total but towards neither succeeded nor failed, so on a project with cancellations those two will not add up to the total — the difference is what was cancelled.

Cancelling is available to every role that can start a deployment — Owner, Admin, Manager and Developer. Viewers cannot. Outside the Console, POST /api/v1/deployments/{id}/cancel does the same thing, as does the cancel_deployment tool for MCP clients.

When cancelling is refused #

Projects created before zero-downtime releases build in place, directly in the directory your site is served from. There is no separate release to throw away, and stopping halfway would leave the site half-updated — so Depfloy refuses to cancel a running deployment on such a project and tells you why. A queued one can still be cancelled, since nothing has started.

Rerun and Rollback #

Rerun #

Rerun is the right tool when a deployment failed because of a transient cause (registry timeout, flaky test, environment quirk) and the code itself is fine. Click Rerun on a failed deployment row, confirm, and Depfloy queues a new deployment at the same commit. Your deployment history grows by one entry.

Rollback #

Rollback returns you to an earlier successful deployment. Use it when a release broke production and you need to revert quickly. Depfloy creates a new deployment that targets the rolled-back commit — your history is preserved, and the rollback itself appears as a new deployment.

PHP-FPM projects can reuse a target release that is still on disk. Node.js, Octane and targets missing from disk use a normal deployment at the selected commit. Rollback does not reverse database migrations.

A reused release skips installation and build steps. Shared environment configuration and database state still apply, so check compatibility with the target code before rolling back.

To roll back:

1. From the Deployments page or the project’s Summary, find a previous successful deployment.
2. Click Rollback on it (or on the active deployment to see a chooser).
3. Pick the target deployment and confirm.

A deployment can be rolled back to if:

• Its status is Deployed
• It has a recorded commit ID
• It is not the currently active deployment

You cannot roll back while another deployment is in progress.

Zero-downtime deployments #

Every deployment in Depfloy is zero-downtime by default. Your application stays available to users throughout the deploy — there’s no service interruption.

How files are laid out #

When you SSH into your server, the project files look like this:

/home/depfloy/{project_id}/
├── current/     # Your active application code
└── shared/      # Persistent files (.env, storage/)

• current/ — the running version of your application. When you run commands manually (php artisan migrate, for example), run them in this directory.
• shared/ — contains your .env file and storage/ directory. These persist across deployments.

Node.js port rotation #

Node.js projects (Next.js, Nuxt, Remix, React Router) use blue/green deployment, which rotates the application’s port between deployments. If you write a custom nginx configuration that references a Node.js project, use the upstream alias rather than a hardcoded port — see Nginx Configuration → Node.js Upstream.

What’s preserved #

• Environment variables — your .env lives in shared/.env and is symlinked into each new release.
• Storage directory — for Laravel, Statamic, and Symfony, storage/ is preserved at shared/storage. Uploaded files, logs, cache — all intact between deployments.
• Custom shared directories — if you defined extra shared paths under Settings, they persist the same way.
• Custom commands — your custom deploy command runs in the new current/ directory after the symlink switch.

What happens on failure #

If a deployment fails, the symlink stays pointing at the previous release. Your site keeps serving the old version. Check the deployment log to see what went wrong, fix it, and either re-push or use Rerun.