Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/getployz/ployz/llms.txt

Use this file to discover all available pages before exploring further.

The branch command forks one namespace into another. It is Ployz’s primitive for creating ephemeral environments — PR previews, staging clones, A/B variants — without duplicating data unnecessarily. Branching is a single atomic operation. The source namespace continues to run unaffected. 
ployzctl branch <subcommand> <source> <target> [flags]

​
Resource modes

When branching a namespace, each resource (service, volume) can be in one of two modes:
ModeMeaning
branchCopy-on-write fork. The resource shares the source’s data until it diverges. For volumes, this is an instant ZFS clone.
freshEmpty or newly created resource. The target starts with no data from the source.
The default is branch for services and fresh for volumes. You can override the default for all resources of a type, or set per-resource overrides by name.

​
Subcommands

Compute the branch plan and return what would be created, cloned, and configured — without applying anything. Use this to inspect the plan before committing.
ployzctl branch preview <source> <target> [flags]
​
source
string
required
The source namespace to fork from.
​
target
string
required
The target namespace to create. Must not already exist.
​
--service-mode
fresh | branch
default:"branch"
Default mode for all services in the branched namespace.
​
--volume-mode
fresh | branch
default:"fresh"
Default mode for all volumes in the branched namespace.
​
--service
NAME=MODE
Per-service mode override. Format: --service myservice=fresh. Can be specified multiple times.
​
--volume
NAME=MODE
Per-volume mode override. Format: --volume myvolume=branch. Can be specified multiple times.
Prepare the branch operation and return a prepared deploy ID without executing it. The prepared ID can be stored and applied later with apply-prepared. This enables two-phase workflows where the branch is computed in CI but applied from a separate process.
ployzctl branch prepare <source> <target> [flags]
Accepts the same flags as preview. The response includes a prepared_deploy_id that you pass to apply-prepared.
Prepared deploys expire. Check the expires_at field in the response and apply before the deadline.
Execute the branch operation atomically. The target namespace is created with services and volumes according to the specified resource modes.
ployzctl branch apply <source> <target> [flags]
​
source
string
required
The source namespace to fork from.
​
target
string
required
The target namespace to create.
​
--service-mode
fresh | branch
default:"branch"
Default mode for all services.
​
--volume-mode
fresh | branch
default:"fresh"
Default mode for all volumes.
​
--service
NAME=MODE
Per-service mode override. Can be specified multiple times.
​
--volume
NAME=MODE
Per-volume mode override. Can be specified multiple times.
Apply a branch operation that was previously computed by prepare. The prepared-deploy-id identifies the prepared plan.
ployzctl branch apply-prepared <prepared-deploy-id>
​
prepared-deploy-id
string
required
The prepared deploy ID returned by branch prepare.
Render the TOML manifest that the branch operation would generate, without applying or preparing it. Useful for auditing or storing the manifest in version control.
ployzctl branch render-manifest <source> <target> [flags]
Accepts the same positional arguments and flags as apply. Outputs the manifest to stdout.

​
PR branching workflow

The following steps show a typical pull request branching workflow, where each PR gets its own isolated environment forked from production.
1

Preview the branch plan

Run branch preview to confirm which services and volumes will be cloned versus started fresh.
ployzctl branch preview production pr-42 \
  --service-mode branch \
  --volume-mode fresh \
  --volume uploads=branch
2

Apply the branch

When the plan looks correct, apply the branch. The target namespace is created atomically.
ployzctl branch apply production pr-42 \
  --service-mode branch \
  --volume-mode fresh \
  --volume uploads=branch
3

Deploy the PR build

Deploy the PR’s container image into the new namespace.
ployzctl deploy service web \
  --image ghcr.io/myorg/web@sha256:newdigest \
  --namespace pr-42
4

Tear down after merge

When the PR is closed, remove the branch namespace. Use deploy with a manifest that removes the services, or drain and remove resources directly.

​
Examples

# Preview what branching production to pr-39 would do
ployzctl branch preview production pr-39

# Apply a branch with default modes (services=branch, volumes=fresh)
ployzctl branch apply production pr-39

# Branch with all volumes cloned (copy-on-write)
ployzctl branch apply production pr-39 --volume-mode branch

# Override a single volume to be fresh while others are branched
ployzctl branch apply production pr-39 \
  --volume-mode branch \
  --volume tmp-cache=fresh

# Two-phase: prepare in CI, apply from deployment system
PREPARED=$(ployzctl --json branch prepare production pr-39 | jq -r '.prepared_deploy_id')
ployzctl branch apply-prepared "$PREPARED"

# Render the manifest without applying
ployzctl branch render-manifest production pr-39

Build docs developers (and LLMs) love

Get started for freeTalk to us