# Git deploy

URL: https://docs.vaultpanel.net/guides/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.

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](https://docs.vaultpanel.net/guides/applications/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](https://docs.vaultpanel.net/guides/websites/git-deploy#build-settings)). |
| 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](https://docs.vaultpanel.net/guides/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.

### Enter the repository and build settings

Fill in the settings described in [Build settings](https://docs.vaultpanel.net/guides/websites/git-deploy#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 `.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 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.

> **Warning:**
A webhook turned on before VaultPanel signed webhooks shows **On, unsigned**: anyone with its URL can start a deployment. Click **Create a new URL** to get a secret, then update the webhook in your Git host.

## 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](https://docs.vaultpanel.net/guides/websites/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.
