Git deploy

Deploy from a Git repository with automatic framework detection, sandboxed builds, health-checked zero-downtime releases, push webhooks and one-click rollback.

Updated Oct 7, 2026 · 5 min read

Git deploy builds and runs your code straight from a repository. ZoPanel detects the framework, proposes install, build and start commands, builds in a sandbox limited to the account's CPU and memory, and only switches traffic to the new release after it passes a health check. If anything fails, the previous release keeps running.

Create a website from Git

1. Open Websites → New website and choose the Git deploy type.
2. Enter the Repository URL, the Branch (default main) and, for monorepos, the Root directory (for example apps/web).
3. Keep Free SSL (Let's Encrypt) on and click Create website.

The first deployment starts immediately. When it has finished, ZoPanel issues the SSL certificate in the same task, so the two never collide.

You can also deploy into an existing website from its Deploy tab.

Repository URLs

The repository host must be a public address. For a private repository, open Deploy → Deploy key (private repositories), click Show deploy key, add that public key to the repository as a read-only deploy key, and use the git@… URL.

Other sources in the Source list: Uploaded files (File Manager), where you upload the project to domains/<domain>/source with the File Manager or SFTP, and Ready-made Docker image.

Framework detection

On every deploy (unless you turn Auto-detect off), ZoPanel inspects the repository and fills in the build settings. The first match wins:

A few details worth knowing:

• Package manager: pnpm-lock.yaml → pnpm install --frozen-lockfile, yarn.lock → yarn install --frozen-lockfile, package-lock.json → npm ci, otherwise npm install.
• Node.js version: taken from .nvmrc, .node-version or engines.node. If that major version is not installed, the newest installed one is used.
• Static exports: Next.js with output: 'export', Astro without @astrojs/node, SvelteKit with adapter-static, Vite, Angular and similar builds are served as static sites from their output folder.
• Procfile: a web: line always provides the start command.
• Laravel: an APP_KEY is generated if missing, storage and .env are kept between releases, and sessions and cache use the account's Redis when it is available.

Click Analyze repository to see the detection before you deploy, then Use these settings and customize if you want to change them.

Build and run settings

The Build & run card shows what will run:

Environment variables are available during the build and at runtime; PORT is set automatically. Use Paste .env to add many at once (up to 200 variables, single-line values).

Container (Dockerfile) mode must first be enabled once on the server by an administrator:

zopanel ctl feature enable custom-docker

How a deployment runs

1. The code is fetched into a new release folder: domains/<domain>/releases/<timestamp>/.
2. Install and build commands run as the hosting account through systemd, inside the account's CPU and memory limits, unable to write outside its home.
3. Server apps start in the idle slot on their own port. ZoPanel waits up to 90 seconds for the health check path to answer.
4. nginx switches to the new release (a graceful reload), then the previous process is stopped. current points to the live release.

Each deployment is listed under Deployments with its commit, trigger (Manual, Git push or Created) and status. If a deployment fails, the owner gets a Deployment failed notification.

Automatic deploys on push

1. On the Deploy tab, turn on Deploy when main is pushed in the Automatic deploys card.
2. Copy the Payload URL (https://<panel-domain>:8888/api/hooks/deploy/<id>) and the Secret.
3. Add the webhook in your Git host:
   • GitHub: Settings → Webhooks → paste the URL, content type application/json, and the secret.
   • GitLab / Gitea: paste the URL and put the secret in Secret token.

ZoPanel verifies the signature (GitHub's X-Hub-Signature-256) or the token header (GitLab, Gitea); the secret is never accepted in the URL. Only pushes to the configured branch deploy. Duplicate deliveries are ignored, and at most one webhook deploy starts per 15 seconds, never while another deployment is running. GitHub's ping event answers pong.

Regenerate secret replaces the secret; update the webhook in your Git host afterwards.

Deploy from CI with an API token

With a Pro license, create an API token in My account → API tokens and trigger a deployment from any CI system:

curl -X POST \
  -H "Authorization: Bearer zpat_..." \
  https://panel.example.com:8888/api/sites/<site-id>/app/deploy

Rollback

The Releases card keeps the last 5 builds. Click Rollback on any of them: server apps are started in the idle slot and switched over after the health check, exactly like a deployment, so rolling back causes no downtime.

Logs

• Deploy tab → Application output shows the latest output of the running app; turn on Live to follow it.
• Each deployment's build log is kept in Tasks.
• The website's Logs tab shows the nginx access and error logs, and Run diagnostics explains recent errors.