Impreza can create a separate app deployment for a branch pushed to an eligible Git-connected parent deployment. The preview receives a Tor v3 onion address without provisioning a public DNS hostname or requesting a public TLS certificate for that address.
This guide covers branch previews, not a permanent Tor site or a copy of your entire production environment. Start with a disposable test app before enabling the workflow for a project used by customers.
Check the supported setup
Use a custom deployment built from an accessible Git repository, with a working push webhook and an available Impreza Agent. Identify the parent deployment ID and its watched branch. A push to that watched branch follows the parent’s normal deployment flow; eligible other branches can create previews.
For the workflow described here, use a repository that can be cloned without private-repository credentials and a Dockerfile at the repository root. The current preview creation path selects that file and does not explicitly carry the parent’s private Git authentication into the child. Do not assume a private repository or custom Dockerfile path works just because the parent deploys successfully. Ask support to confirm those configurations before relying on them.
Compose manifest mode is not supported for previews. Tags do not create branch previews. A generic webhook must include a supported branch ref such as refs/heads/feature-demo; a request without that information is not a branch-preview trigger.
Prepare test settings and capacity
Previews run on the same server as their parent and inherit its CPU and memory settings. Reserve capacity for the parent, concurrent previews and builds. A preview count limit is not a guarantee that the VPS has enough resources.
The preview gets its own deployment storage for supported declared volume paths. It does not automatically copy the parent’s stored data. Most app environment variables are inherited, however: removing the parent’s domain and deployment identifiers does not remove database URLs, API keys or payment credentials.
Use a separate test parent configured with test credentials and non-production dependencies when needed. Review background workers, emails, payments, webhooks and external databases before enabling previews. Separate local storage does not prevent a child from contacting the same external service as its parent.
Configure the parent
Use impreza_git_webhook_status to confirm the push connection and watched branch. Use impreza_list_previews with the parent deployment ID to read its settings and current previews.
To enable a small test configuration, pass the following arguments to impreza_configure_previews, replacing the placeholder ID:
{
"deployment_id": "dpl_PARENT_REPLACE_ME",
"enabled": true,
"ttl_hours": 24,
"max": 2
}
Read the returned settings. The supported lifetime is 1–168 hours, with a default of 24. The maximum concurrent count is 1–20, with a default of 5. Supply both numeric settings when changing the configuration so your intended limits are explicit.
Push a branch and collect its address
Push a test branch other than the watched branch. Then call impreza_list_previews with the parent ID and check the matching branch, deployment status, onion address and expiry.
A successful webhook response can contain a note explaining that no preview was created. An event or an accepted deployment request is not proof that the app has finished building. Wait for a running deployment and test the page before sharing the address.
Open the returned address in Tor Browser. Check application login, navigation, assets and the intended change. A normal browser or an external integration without Tor support will not use an onion URL directly.
Further pushes to the same live preview branch redeploy it and extend its expiry. The existing preview keeps its address while it remains alive. A new deployment after retirement should be treated as a new preview with a new address.
Understand what private means here
The generated onion address avoids a public preview hostname and its associated public certificate request. It is not an invitation-only access control. Anyone who obtains an ordinary onion address may be able to open the app unless the application requires authentication.
Use app login for restricted reviews. Tor client authorization is a separate mechanism; this workflow does not establish that it is configured. Avoid sensitive data and external scripts that expose the review elsewhere. Do not publish the onion URL in public issues or logs.
The account and Git provider still hold deployment or repository information. Configured event receivers may receive the branch and onion address. Also check host-port and firewall exposure for your server before making a claim that the app is reachable exclusively through Tor; the absence of a public hostname alone does not establish that.
Close the review and verify cleanup
The TTL is extended after another push to the live preview branch. Expiry is handled by a cleanup process; do not assume teardown occurs at the exact second on the timestamp.
An authenticated branch-deletion push requests retirement. Merging a pull request without deleting its branch is not the same signal. When a new preview would exceed the count limit, the oldest existing preview is selected for retirement.
Turning previews off leaves existing previews running until they expire or are retired. To request early retirement, call impreza_retire_preview with the preview’s deployment ID, not the parent’s. It requires manage access. Check the lifecycle result and confirm the old endpoint no longer serves the app. Do not treat retirement as proof that every data copy or log was erased.
For choosing a server and review workflow, see private preview environments. For diagnostic checks, use the app inspection guide.