Enforced remote builds and deploy by digest

Dokploy can already point an application at a build server and a registry. Dokploy Community Edition adds an organization-wide build policy on top: one setting that makes Dokploy the only builder for your applications sourced from github.com. The build runs on your build server, the image is pushed to your registry, and the swarm service is updated by digest, so CI can wait for that exact image instead of building a second copy. Upstream Dokploy v0.30.8 has no build policy. The fork adds it, and it is off by default.

See also the home page, the FAQ and the related deploy queue controls.

What it does

With enforcement on:

1. An application sourced from github.com builds on the organization’s default build server. There is no silent fallback to a local build.
2. The image is pushed to the organization’s default registry as <repository>:<sha>.
3. Dokploy reads back the image digest and updates the service by that digest. If no digest is published, the deploy fails instead of deploying a mutable tag.
4. The digest and tag are stored on the deployment, so a later rollback can reuse them.
5. Pull request previews follow the same path.

The other parts of the policy are separate, opt-in controls:

• Exclusions keep chosen applications on a local build.
• Break-glass lets one deploy build locally once, with a recorded reason.
• Required checks make a deploy wait for named GitHub check runs or commit statuses on the commit. They only take effect while Enforce Remote Builds is on, and only for a unit sourced from github.com and connected through a GitHub App provider; saving checks on any other unit is refused. An exclusion does not bypass them.
• Coalescing folds a burst of pushes into one waiting deploy.
• Rollback to a digest redeploys a past application image without building.

Set it up

You need a server of type build, a registry, and an admin account.

1. Add the build server and the registry in Dokploy as usual.
2. Open Settings, Server and find the Build Policy card.
3. Choose the Default Build Server and Default Registry.
4. Set Required Checks Timeout (minutes) if you plan to use required checks (1 to 720, default 5).
5. Turn on Enforce Remote Builds and save.

Read the next section before step 5.

What changes when you turn it on

• Derived watch paths start filtering pushes. A unit with no explicit watch paths now only deploys for changes under the directories it builds from: the build path, the Dockerfile and context directories, or the Compose file’s directory. In a monorepo, a push that only touches shared code stops at the webhook and creates no deployment. Set explicit watch paths first. Each skipped push is written to the audit trail with the paths involved.
• Every application sourced from github.com moves to the build server. That means a GitHub App source or a plain git remote on github.com; GitHub Enterprise hosts are not included. Add exclusions for anything that must keep building where it is before you flip the switch.
• Queued deploys coalesce. A burst of pushes leaves one waiting build at the earliest position, carrying the newest commit. Previews are never coalesced.
• A [skip deploy], [deploy skip] or [no deploy] marker in a commit message is honored on push-triggered deploys (not on tag pushes or previews).
• A deploy-hook body with an image is no longer ignored. On an application it is validated and must name the application’s own repository.

The push gate (watch paths, skip markers and coalescing) covers every unit in an organization that enforces, whatever its source and including Compose. Moving the build to the build server and deploying by digest apply only to units sourced from github.com.

With enforcement off, none of this applies and deploys behave as in upstream Dokploy.

Exclusions and break-glass

An admin can exclude an application from enforcement under Settings, Server (Build Policy Exclusions), with an optional reason. Compose builds are never moved to the build server by this policy, so exclusions apply to applications only.

For a one-off local build, the admin-only buildPolicy-allowLocalBuildOnce API and MCP tool records a grant with a required reason. The next deploy of that application consumes the grant, and both events are written to the audit trail.

Required checks

Required checks need Enforce Remote Builds on, and a unit sourced from github.com that is connected through a GitHub App provider (a plain git remote has no App installation to read checks with). On an application, the Required Checks card on the Advanced tab takes the names of checks that must pass on the commit before the build starts. A Compose service takes the same list through the requiredChecks field of the Compose update API. Names are matched against both GitHub check runs and legacy commit statuses. If a check fails or the timeout passes, the deploy fails and says which.

Limit: the wait occupies a deployment slot. A self-hosted instance has the builds concurrency setting of them (default 1), so one unit waiting on a check that never arrives queues every other deploy behind it. Raise the build concurrency before raising the timeout.

Roll back by digest

The admin-only buildPolicy-rollbackToDigest takes the id of a past application deployment and redeploys the image that deployment stored, with a pull and a service update and no build. Compose deployments are not covered. It does not re-run required checks. A deployment from before enforcement has no stored digest and is refused.

Audit trail

Admins can read the policy audit trail, which records settings changes, exclusions, break-glass grants and use, enforced builds, skipped and coalesced deploys, failed or timed-out checks, and deploys by digest.

Limits

• Relocated builds and digest deploys cover applications sourced from github.com. Required checks also apply to Compose services.
• Admin access is required to change settings, exclusions and grants, to roll back by digest and to read the audit trail. Over MCP these tools need the dokploy:admin scope, so a default OAuth grant cannot call them.
• Build servers, registries and the registry cleanup are yours to run. The policy does not garbage-collect the registry.

Source

• Build policy module and its README
• Changelog entry (build once, deploy by digest, PR 209)