Deploying a site from GitHub or GitLab

A domain's Git & apps tab publishes the site from a Git repository. Each deploy copies the branch into the site's folder. Files you uploaded yourself are left alone.

Connecting a repository

1. Open the domain's Git & apps tab.
2. Fill in Repository and Branch (main by default).
   • For a private repository, use the SSH address, such as git@github.com:you/site.git.
   • A public repository can use its https:// address. Don't put a username or token in it.
3. Optionally set Deploy into (a folder inside the site's document root; empty means the root) and Publish folder from the repository (such as dist or public; empty means the whole repository).
4. Press Connect repository.

Adding the deploy key

After connecting, the tab shows a Deploy key unique to this domain. Press Copy and add it to the repository as a read-only deploy key:

• GitHub: the repository's Settings → Deploy keys → Add deploy key. Leave Allow write access unticked.
• GitLab: the project's Settings → Repository → Deploy keys.

Then press Deploy now. If the deploy says "Fetching the repository failed", check the address, the branch and the key.

New key replaces the key. The old one stops working, so add the new one to the repository.

Deploying on every push

Tick Deploy automatically when the branch is pushed (webhook) (under Edit settings once connected), then add a push webhook in the repository with the Webhook URL and secret from the tab:

• GitHub: Settings → Webhooks → Add webhook. Paste the URL, set the content type to application/json, paste the secret, and choose "Just the push event".
• GitLab: Settings → Webhooks. Paste the URL, paste the secret as the Secret token, and tick Push events.

Gitea and Forgejo webhooks work too, with the same URL and secret.

Pushes to other branches are ignored. If several pushes arrive while a deploy is waiting, only the newest commit is deployed. New secret replaces the secret; pushes stop deploying until you update it in the repository.

Keeping files a deploy mustn't touch

Remove files that were deleted from the repository (on by default) deletes only files an earlier deploy put there. Anything else in the folder stays.

Never overwrite or remove protects paths from deploys altogether, one per line, relative to the deploy folder. * works as a wildcard:

.env
uploads
wp-content/uploads

On the first deploy, Hostctl's own placeholder page is removed.

Running build commands

Build commands (optional) run in the repository before its files are copied, one per line, stopping at the first that fails:

composer install --no-dev
npm ci
npm run build

They run as the site's own user, in a sandbox that can reach the internet but not this server's databases or other services. php is the domain's PHP version. Composer and Node.js come from your host's build tools; if they aren't installed, the tab says so. Each step can run for up to 15 minutes.

Build commands need an isolated hosting account. On an older shared account the field is greyed out, and deploys copy files without building.

Choosing a Node.js version for builds

Node.js for builds picks the Node.js that node, npm and npx run during the build: one of the Node.js LTS releases installed on the server, or Ubuntu's (Build Tools). It only appears when your host has installed those releases.

Rolling back

Every deploy appears under Deploys with its commit and log. To go back, press Redeploy on an earlier successful deploy. That commit is deployed again, with the same rules as any deploy. Databases aren't changed.

A deploy can't be bigger than 200,000 files or 5 GB. Cancel deploy stops one that's running.

Clearing the cache or disconnecting

• Clear build cache makes the next deploy fetch the repository and dependencies from scratch. Afterwards, files that earlier deploys published are no longer tracked, so a later deploy won't remove them if the repository drops them; delete those by hand.
• Disconnect repository removes the deploy key, webhook and deploy history. The site's files stay.

To run the repository as a Node.js server instead of publishing files, see Running a Node.js app.