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.
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
- 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:
| Stage | What happens |
|---|---|
| Prepare | The site's release folders are checked. |
| Clone | The branch is cloned into a new release folder. |
| Install | Dependencies are installed (see Install command). |
| Build | Your build command runs. |
| Publish | The output folder is found and current is switched to it. |
| Health check | The 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,yarnorpnpmcommands, 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.
Enter the repository and build settings
Fill in the settings described in Build settings.
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
| Setting | Notes |
|---|---|
| Git repository | An 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. |
| Branch | The branch to deploy. Defaults to main. |
| Output folder | The 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 command | Optional. Static sites: such as npm run build; empty for plain HTML. PHP sites: runs after Composer, such as php artisan config:cache. |
| Install command | Optional. 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 keep | 1 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
.envfile, where Laravel and Symfony read them, when the site serves an output folder (such aspublic) and the repository has no.envfile 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 host | How the request is signed |
|---|---|
| GitHub, Gitea, Forgejo, Bitbucket | An HMAC-SHA256 of the body in X-Hub-Signature-256, X-Gitea-Signature or X-Forgejo-Signature. |
| GitLab | The 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.
File manager
Browse, edit, upload and download a website's files in the browser, unpack and create archives, and change permissions, all as the site's own Linux user.
Uptime monitoring
How the panel checks each website the way visitors reach it, records uptime and downtime, and raises the Website down alert when a site stops answering.