Git deployments

Put a site live from a Git branch instead of uploading files. Each deploy fetches the branch from GitHub, GitLab, Gitea, Bitbucket or any Git server, runs your build commands (Composer, npm, Artisan...) as the hosting account in a new release, and switches the site to it in one step. A push can deploy automatically, and going back to an earlier release takes a click.

How a deploy works

1. Fetch. The server keeps a copy of the repository in ~/apps/<domain>/repo.git and fetches the new commits.
2. New release. The branch is unpacked into ~/apps/<domain>/releases/<time>/, without the .git folder.
3. Shared files. The paths you list as shared, such as .env or storage/, are linked into the release from ~/apps/<domain>/shared/, so they survive every deploy.
4. Build. Your build commands run in the release as the account, with the account's PHP version. The first command that fails stops the deploy, and the site stays as it was.
5. Switch. ~/apps/<domain>/current is pointed at the new release in one step, so visitors never see a half-copied site. The site's document root (public_html, or the addon domain's folder) points at current, or at its public folder.
6. Health check (optional). A page you choose, like /, must answer. If it does not, the site goes back to the previous release by itself.
7. Clean up. Old releases beyond the number you keep (5 by default) are removed.

On the first deploy, the files the site had are moved aside to <document root>.before-deploy-<time>. Nothing is deleted. The document root keeps its path, so backups, the WordPress Toolkit and the file manager keep working as before.

A deploy runs in the background with limits on memory (2 GB), processes and time (30 minutes). Only one deploy of a site runs at a time. Pushes that arrive meanwhile are merged into one next deploy.

The Deployments page

Each site on the page is a card with two halves:

Settings on a card opens the same form as New deployment. Below the sites, Runtimes installs and updates the Node.js and Python versions apps use.

Setting one up

1. New deployment: choose the site.
2. Optionally pick a Start from preset. It fills in the settings below, and you can change anything after.
3. Code from Git: give the repository address and branch, and the build settings. Switch it off to keep the files uploaded to the site, for example for a Node.js app you upload over SFTP.
4. Runtime: PHP serves the site with its PHP-FPM pool, as before. Choose a Node.js or Python version to run the site as an app, and give its start command.
5. Create, then Connect shows what to paste into your Git host:
   • the site's deploy key, which gives read access to a private repository (GitHub: Settings > Deploy keys; GitLab: Settings > Repository > Deploy keys; Gitea: Settings > Deploy Keys);
   • the webhook address and secret, for deploys on push. Use content type application/json and push events. On GitLab the secret goes in Secret token.
6. Deploy puts the branch live. The log follows the deploy as it runs. An app on the site starts with its first deploy.

Use the SSH address of a private repository (git@github.com:you/site.git). An HTTPS address needs no key, so it suits public repositories.

In Settings, switching Code from Git off stops deploying (the site keeps its current release). Setting the runtime back to PHP removes the app, and the domain is served by PHP again. Remove does both. The files always stay.

Start from

A preset fills in common settings for a kind of site. Nothing is saved until you press Create or Save.

The Node.js and Python presets need that runtime installed first (Runtimes at the bottom of the page). They are offered only with nginx in front. Change the start command to match your app: for example node server.js, or .venv/bin/uvicorn main:app --host 127.0.0.1 --port $PORT for FastAPI. For Django, use gunicorn with your project's wsgi module.

Git settings

Rolling back

Roll back lists the releases on disk with their commits. Choose one and the site switches to it at once. Nothing is rebuilt, and the shared files stay as they are. The next deploy puts the branch live again. A database migration is not undone by a rollback.

Webhooks

Git hosts call https://<server hostname>/.reqad-deploy/<id> on port 443. A webhook starts a deploy only when it is signed with the deployment's secret (GitHub, Gitea/Forgejo and Bitbucket sign it; GitLab sends the secret as its token). The panel port 2087 can stay closed to the internet (Settings > Security > IP restriction). Webhooks need nginx in front.

From a CI pipeline, call the API instead. Use an API token with the write permission; a token for the site's account is enough:

curl -X POST -H "Authorization: Bearer $REQAD_TOKEN" https://server.example.com:2087/api/v1/deployments/shop.example.com/deploy

Good to know

• Build commands run as the hosting account, never as root, with the same access as the account's own PHP. composer, npm and node are the server's.
• A Node.js or Python app on the domain restarts after each deploy. If it does not start, the deploy goes back to the previous release.
• Git submodules are not fetched.
• No other site of the account may have its document root inside a deployed one, because each deploy replaces that folder. Creating such an addon domain is refused.
• Releases count toward the account's disk usage and its backups. Lower Releases kept for big builds (e.g. node_modules).
• The last deploy failing shows on the dashboard's Needs attention card.
• Delete stops deploying. The site keeps running from its last release, and its files stay in ~/apps/<domain>.

On the command line

reqad deploy create shop.example.com --repo=git@github.com:you/shop.git \
    --dir=public --shared=".env,storage/" --check=/ \
    --build="composer install --no-dev --optimize-autoloader
php artisan migrate --force"
reqad deploy run shop.example.com --wait      # follow the output
reqad deploy rollback shop.example.com        # to the release before
reqad deploy list
reqad deploy log shop.example.com

See Command line (CLI) for every option.

Need a hand? Create a free account or contact us.