Deploy a website from GitHub

A deploy makes the site’s web root an exact copy of one branch of a GitHub repository, or of one folder in it. It works with public and private repositories, and can run automatically on every push through a webhook.

Before you start

• Your account has the Edit hosting config permission.
• The site is a static or PHP hosting without WordPress. The Deploy from GitHub card is not shown for WordPress, proxy or redirect sites.
• The node that hosts the site has git, rsync and sudo, plus ssh if you use a deploy key. If any is missing the card says Missing … and Deploy now is disabled. Run update.sh on the node; it installs them.
• The repository’s address and branch, and for a private repository the means to add a deploy key or create a token on GitHub.
• For automatic deploys, GitHub can reach the panel’s address over HTTPS.

Steps

1. Open the site’s Overview tab and find Deploy from GitHub.
2. Fill in the connect form:
   • GitHub repository. Paste the address from the browser: https://github.com/owner/repo, an address ending in .git, an owner/repo page with /tree/<branch> and ssh addresses all work. Only github.com is accepted.
   • Branch. Blank means main.
   • Folder to publish, optional. Its contents become the web root, for example public or dist. Blank publishes the whole repository.
   • Access: Public repository, Deploy key (recommended for private repositories) or Access token.
   • Deploy automatically on every push to this branch, optional.
3. Click Connect repository. Nothing is deployed yet.
4. Give the node access, depending on the choice:
   • Deploy key: the card shows a Public key. On GitHub open the repository, then Settings → Deploy keys → Add deploy key, paste the key and leave Allow write access unticked. A key added to another repository or to a user account does not count.
   • Access token: create a fine-grained token for this one repository with Contents: Read-only, paste it into Personal access token and save. The token is stored on the site’s node only.
5. In the Access row, click Test access. A green line says “This node can read owner/repo and its branch main.” and shows the commit.
6. If you ticked automatic deploys, the Auto-deploy row now shows a Payload URL and a Secret. On GitHub open the repository, Settings → Webhooks → Add webhook, paste both, set the content type to application/json and choose Just the push event.
7. Click Deploy now.

Before the first deploy

The first deploy replaces the web root: every file there that is not in the repository is deleted, including uploads and a .user.ini written by PHP settings on the site’s Settings & limits tab. Every later deploy also removes files added by FTP or in the file manager. A confirmation dialog titled Replace this site’s files? appears.

Confirm a backup first: open the site’s Backups tab and check that the newest archive has the state ok and a plausible size. To undo, restore that archive. Commit everything you want to keep, such as .user.ini, to the repository first.

The deploy runs as a background job under the site’s own Linux user. It fetches only the newest commit of the branch (depth 1), discards anything untracked, mirrors the tree into the web root with rsync --delete and leaves .git out, so history is never served. The checkout lives in a hidden directory in the site’s home. The page cache is purged afterwards.

Only one deploy per site runs at a time. A push that arrives during a deploy queues one follow-up; the follow-up fetches whatever is newest when it starts. Only pushes to the configured branch deploy. A deploy takes at most 10 minutes for the network steps before it is stopped.

To change repository, branch, folder, access or auto-deploy later, open Change repository, branch, access or auto-deploy. Replace this key with a new one makes a fresh deploy key and stops the old one at once.

To stop, open the same section and click Disconnect. Hyperion forgets the repository, key, token, webhook secret and history, and removes its checkout. The site keeps the files it has. Remove the deploy key and the webhook on GitHub too.

Check that it worked

The card’s heading reads deployed <commit> · <time> ago. Deploys shows the live commit with its message, and Recent deploys keeps the last 10 with the trigger (manual or push) and who ran it.

ls /home/<system-user>/<domain>/htdocs

Expected: the repository’s files, with no .git directory.

If it fails

The card shows the cause in plain words and a What git said fold.

• GitHub refused access: the repository is private, or it does not exist. For a private repository choose Deploy key or Access token. Public access was chosen for a private repository.
• GitHub found no repository this deploy key may read. Add the key to this repository’s Deploy keys.
• GitHub refused the access token. The token expired or lacks Contents: Read-only on this repository.
• The repository has no branch named “main”. Correct Branch.
• Check the webroot sub-directory setting. The branch has no such folder; fix Folder to publish.
• This node could not reach github.com — check its DNS and outbound firewall.
• A deploy of this site is already running. Wait for it to finish.
• A webhook returns a failure on GitHub: 401 bad signature means the Secret differs; 404 auto-deploy is off means the tick box is off. Pushes to other branches answer 200 not the deploy branch.

Related

• Update Hyperion