Websites

Git deploy

Deploy static and PHP websites from a Git repository into release folders, with builds, environment variables, instant rollbacks and signed push-to-deploy webhooks.

Last updated

Instead of uploading files, a static or PHP website can deploy from a Git repository. Each deployment clones the repository on the server, runs your install and build commands, and switches the site to the new release. The newest releases stay on the server, so a rollback is instant, and a push to your branch can deploy by itself.

Git deploy is optional and set per website. Apps (Node.js, Python, Go, Ruby) deploy from Git on their own: see Deployments.

How it works

current → releases/20261021094210-d4e5f6/dist
  • Each deployment goes into its own folder under releases/.
  • The site serves current, a link to the live release's output folder. NGINX (and PHP-FPM for PHP sites) follow the link.
  • The files the site served before, usually public/, are kept. The site serves them again if you turn Git deploy off.
  • .ssh/ holds the site's deploy key for private repositories.

A deployment goes through these stages, as the site's own Linux user:

StageWhat happens
PrepareThe site's release folders are checked.
CloneThe branch is cloned into a new release folder.
InstallDependencies are installed (see Install command).
BuildYour build command runs.
PublishThe output folder is found and current is switched to it.
Health checkThe agent checks that the site still answers.

A deployment that fails before the switch leaves the live release untouched. One whose site stops answering after the switch is switched back.

Requirements

  • A static or PHP website. See Websites.
  • Git on the server: install it from the App runtime card on the server page's Applications tab.
  • For PHP sites with a composer.json, Composer on the server (optional software, from the same card).
  • For npm, npx, yarn or pnpm commands, Node.js installed system-wide on the server. A Node.js installed in a home folder (for example by nvm) cannot be used.
  • Agent 0.22.0 or newer for static sites, 0.24.0 or newer for environment variables, 0.32.0 or newer for PHP sites.

Turn on Git deploy

Open the Deployments tab

Open the website and go to its Deployments tab.

Turn it on

Click Turn on Git deploy. With Deploy now ticked, the first deployment starts as soon as the site's release folders and deploy key are set up. For a private repository over SSH, leave Deploy now off: add the deploy key to the repository first, then deploy.

Build settings

SettingNotes
Git repositoryAn https:// URL for a public repository, or an SSH address such as git@github.com:you/site.git for a private one. Passwords in the URL are not accepted.
BranchThe branch to deploy. Defaults to main.
Output folderThe folder that is served after the build. Static sites: such as dist or build. PHP sites: the folder with index.php, such as public for Laravel and Symfony, so the rest of the repository stays out of reach of visitors. Empty serves the repository as it is.
Build commandOptional. Static sites: such as npm run build; empty for plain HTML. PHP sites: runs after Composer, such as php artisan config:cache.
Install commandOptional. Empty: PHP sites get composer install when there is a composer.json. When there is a build command and a package.json, npm installs the dependencies (npm ci with a lockfile, otherwise npm install).
Releases to keep1 to 20; default 5. Older releases are removed after each deployment. The live and previous releases are always kept.

Commands run one per line, up to 10 lines of up to 500 characters each, as the site user. They run without a shell, so |, &, ;, <, >, backticks and $( are refused: put each command on its own line instead. Blank lines and lines starting with # are skipped.

The settings are saved at once and used by the next deployment.

Private repositories

Each website has its own deploy key. Once Git deploy is set up on the server, the Deploy key card shows its public key. Add it to the repository as a read-only deploy key (on GitHub: Settings > Deploy keys), and use the repository's SSH address.

Environment variables

The website's Environment tab holds variables for its deployments, stored encrypted in the panel. They are given to the install and build commands.

  • Static sites: a build copies the ones it uses into the site's files, so visitors can read them. Do not put passwords or private keys here.
  • PHP sites: they are also written to the release's .env file, where Laravel and Symfony read them, when the site serves an output folder (such as public) and the repository has no .env file of its own.

Saved variables are used by the next deployment.

Deploy and roll back

  • Deploy now on the Deployments tab starts a deployment of the branch's latest commit.
  • Each row in the deployments list shows the commit, how it started (Manual, First deploy, Git push or Rollback), its status and duration. The live release is marked Live.
  • Roll back switches the site to an earlier release that is still on the server. Nothing is rebuilt.

While a deployment runs, the website shows Applying changes and other changes wait.

Push to deploy

With push to deploy, each push to the website's branch deploys it. The webhook works with GitHub, GitLab, Gitea, Forgejo and Bitbucket, and every request must be signed with the webhook's secret.

Create the webhook

On the Deployments tab, in the Push to deploy card, click Turn on. VaultPanel shows a Webhook URL and a Secret once: copy both now.

Add it to your repository

In your Git host, add a webhook with:

  • the Webhook URL as its address,
  • content type application/json,
  • push events,
  • the Secret in its secret field (GitLab: Secret token).

The URL has the form https://panel.example.com/api/v1/hooks/deploy/<token>, built from the panel's address. Pushes to other branches and other events are ignored, and a ping is acknowledged without deploying.

Git hostHow the request is signed
GitHub, Gitea, Forgejo, BitbucketAn HMAC-SHA256 of the body in X-Hub-Signature-256, X-Gitea-Signature or X-Forgejo-Signature.
GitLabThe secret itself in X-Gitlab-Token.

A request without a valid signature is refused and recorded in the audit log. If the URL or secret leaks, click Create a new URL: the old URL stops working. Turn off removes the webhook.

Turn off Git deploy

Turn off Git deploy on the Deployments tab stops deployments, rollbacks and push to deploy, and the webhook URL stops working. The site serves the folder it served before Git deploy was turned on, with the files it had then, and you manage it with the file manager again. Releases stay on the server until the website is deleted.

While Git deploy is on, the website's type cannot change, and its document root is the live release: set the folder to serve with Output folder instead.