Deploy

Deploy is how Divine promotes the work an agent did in a worktree into your app theme. A worktree is a git-backed copy of the app theme under its own directory, so building in it never touches the live theme. Deploy is the deliberate step that moves the accepted files across, replaces the app theme’s contents with them, and then removes the worktree it came from.

Why Promote Files Instead Of Switching Themes

A worktree is a real WordPress theme on disk, so it would be tempting to ship by simply activating it. Divine does not work that way. Your app theme is the stable identity the live site serves, and the worktree is a disposable workspace whose slug, registry record, and preview session exist only while you are iterating. Activating worktrees would leave the live site pointed at an ever-changing pile of throwaway themes.

Deploy keeps the app theme as the durable target. It mirrors the worktree’s files into the app theme directory, so the theme that visitors already see keeps its slug and its own git history while gaining the new work. After the mirror, the worktree has served its purpose and is destroyed. Promotion is final for that worktree; the next change starts from a fresh one.

In the workspace, deploy appears in the merge panel after you have reviewed the diff. Over REST it is POST /wp-json/divine/v1/apps/<app>/worktrees/<id>/deploy. Both paths require Divine’s management capability.

What Happens During Deploy

Deploy runs a fixed sequence so a half-finished promotion never reaches the app theme.

1. Any resolved files submitted with the deploy are written into the worktree first, so conflict resolutions you accepted in the merge view become part of the source.
2. Divine inspects the worktree’s git state.
3. If git still reports conflicted files, deploy stops with a validation error and writes nothing to the app theme.
4. The worktree’s contents are mirrored into the app theme directory.
5. The app theme’s own .git directory is preserved, so the theme keeps its history.
6. The worktree theme directory and its registry record are removed.
7. The divine/worktree/deployed action fires.

The deploy result reports the worktree id, the destruction result, the resolved app slug, the target blog_id, and the app theme path.

Files Only, Never The Database

Deploy promotes files and nothing else. Pages, blocks, templates, patterns, assets, PHP, style.css, divine.json, and any other normal theme file travel from the worktree into the app theme. Because the mirror replaces the app theme’s contents, a file you deleted in the worktree is deleted in the app theme too.

Deploy never copies database state. It does not move WordPress posts, options, terms, uploads, or plugin data, and it does not promote a database sandbox, because a Divine worktree is a theme file workspace, not a database branch. This is a hard boundary: the only thing that crosses from a worktree to your app theme is theme files.

Divine also does not create a git commit during deploy. The app theme repository receives file changes, and committing them stays part of your normal workflow.

Multisite Targets One Site

On a multisite network, a Divine app is one network site with its active theme, and blog_id is part of the deploy target. Deploy resolves the app for the worktree, confirms the worktree belongs to that app, and mirrors files into that site’s active theme only. It does not fan changes out across the network or touch any other site’s theme. The deploy result carries the normalized blog_id so the promotion is unambiguous about which site received the files.

Conflicts Block Deploy

If git reports conflicted files in the worktree, deploy fails with a validation error rather than guessing which side wins. Resolve each conflicted file in the merge view by accepting one side, both, or an edited result, then deploy again. The resolutions you submit are written into the worktree before the conflict check runs, so a clean resolution lets the same deploy proceed.

Destroy

Destroy is the cleanup path for abandoned worktrees and the final step of a successful deploy. It deletes the worktree’s copied theme directory, removes its registry record, and fires divine/worktree/destroyed.

Destroy is available in the worktree sidebar and over REST with DELETE /wp-json/divine/v1/apps/<app>/worktrees/<id>. Once the registry record is gone, that worktree’s preview session and share links stop resolving, because there is no longer a record to sign previews against.

Lifecycle Actions

Both lifecycle events are part of Divine’s public API and fire after the underlying operation has already completed, so consumers use them for follow-up work, not to veto anything.

Action	Fires when	Receives
divine/worktree/deployed	A worktree’s files have been promoted into the app theme.	The worktree id, the deployment input, and the deployment result.
divine/worktree/destroyed	A worktree has been removed, including as the last step of a deploy.	The worktree id and the destruction result.

Use divine/worktree/deployed to invalidate caches or refresh previews after a deploy, and divine/worktree/destroyed to clear preview state or metadata tied to the removed worktree. Treat the worktree filesystem as gone inside the destroy callback, and queue any expensive work outside the request.

After Deploy

After a successful deploy, the app theme contains the merged files and the live site serves them on the next request if that theme is active. Static prerender caches are purged through the worktree lifecycle hooks, the worktree’s preview sessions stop working, and the workspace returns to the app view. When the theme is ready to hand to a client, the next step is to export it as a standalone deliverable.