Deploy from Git

PHP, Laravel, Node.js and static websites can be deployed from a Git repository. Each deploy builds a new release on the server and switches the website to it in one step. Earlier releases are kept, so you can roll back.

Open the website and go to Hosting › Deployments. Other website types don’t have this section.

Note

The Owner and Super admins connect the repository, change its settings and environment variables, and set up push to deploy. Once it is connected, anyone with access to the website, collaborators included, can deploy, read the logs and roll back.

Connect a repository

1. Click Connect a repository.
2. Choose the Provider: GitHub, GitLab or Bitbucket.
3. Under Repository address, paste the repository’s SSH address, such as git@github.com:owner/repository.git. Its HTTPS address works too: Netkeel still fetches the code over SSH with the deploy key. The address must be on the provider you chose.
4. Type the Branch to deploy, such as main.
5. Check the Preset. It starts from the website’s type and fills in the fields below. You can change any of them:
   • Publish directory: the folder visitors are served from, such as public or dist. Leave it empty for the repository root. A Laravel website always needs one, normally public.
   • Releases to keep: 2 to 10, 5 at first. Older releases are removed; you can roll back to the ones kept.
   • Build commands: one per line, up to 10. They run in the new release, as the website’s own user, before it goes live.
   • Shared paths: one per line, up to 20. Files and folders kept between releases, such as uploads, .env or storage.
6. Click Connect repository.

Netkeel sets up the repository on the server and creates its deploy key. Until your first deploy, the website keeps serving the files it already had.

Which presets each type offers

• PHP and Laravel websites: PHP or Laravel.
• Node.js websites: Node.js.
• Static websites: Static.

On PHP, Laravel and static websites, Node.js is available to the build when a build command uses npm, npx or node. A Node.js website builds with its own Node.js version.

What each preset fills in

Preset	Build commands	Shared paths	Publish directory
Static	None	None	Repository root
PHP	None	None	Repository root
Laravel	composer install --no-dev --optimize-autoloader --no-interaction	.env, storage	public
Node.js	npm ci, npm run build --if-present	.env	Repository root

With the Laravel preset you can also choose what runs After each deploy: Run php artisan migrate --force (off at first) and Clear and cache config, routes and views (on at first).

Add the deploy key to your repository

Once the repository is set up, the Deploy key card appears under Hosting › Deployments, below the Repository card. The server uses this key to fetch your code and only needs to read the repository. Each website has its own deploy key.

1. Click Copy key.
2. Click Open the deploy key settings on GitHub (or GitLab, or Bitbucket).
3. Add the key:
   • GitHub: Settings › Deploy keys › Add deploy key. Give it a title, such as Netkeel, and leave Allow write access unticked.
   • GitLab: Settings › Repository › Deploy keys › Add new key. Leave Grant write permissions to this key unticked.
   • Bitbucket: Repository settings › Access keys › Add key. Access keys are always read-only.

Add the key to the same repository as the one on the Repository card.

Deploy

Under Deploy, click Deploy now. Netkeel builds the latest commit of the branch. To deploy a particular commit, type its hash (7 to 40 characters) under Commit first.

While it runs, the card shows each step: Fetching code, Running build commands, Running migrations (only when switched on), Switching to the new release and Removing old releases. Click View log to follow the output.

If a build command or a migration fails, the website stays on the release it was on. On a Node.js website, a new release must also answer on the app’s health check path, or the website goes back to the previous release; see Node.js.

Deploy automatically on push

Push to deploy builds and switches to each commit you push to the branch, with no click in Netkeel. It is off until you set it up.

1. Under Push to deploy, click Create webhook.
2. Copy the Webhook address and the Secret (on GitLab, the Secret token). The secret is shown only this once; if you lose it, click Replace webhook to get a new address and secret.
3. Click Open the webhook settings on GitHub (or GitLab, or Bitbucket) and add the webhook:
   • GitHub: Settings › Webhooks › Add webhook. Paste the address under Payload URL, choose application/json as the Content type, paste the secret under Secret, choose Just the push event and click Add webhook.
   • GitLab: Settings › Webhooks › Add new webhook. Paste the address under URL and the secret under Secret token, tick Push events (you can limit them to your branch), keep SSL verification on and click Add webhook.
   • Bitbucket: Repository settings › Webhooks › Add webhook. Give it a title, such as Netkeel, paste the address under URL and the secret under Secret, choose Repository push as the trigger and click Save.
4. Click Done, then turn on Auto-deploy on push to your branch.

From then on, each push to the branch deploys its latest commit. Pushes to other branches, tags and other repositories are ignored. If you push while a deployment is running, Netkeel waits for it to finish, then deploys the newest commit of the branch once, however many pushes came in between.

Deployments started by a push show Push as their trigger in Deployment history, with the name of the person who pushed.

Recent deliveries

Recent deliveries lists the last 20 messages your Git provider sent, with the time, event, branch, commit and what Netkeel did:

• Deployed: the push started a deployment.
• Queued after the running deploy: a deployment was already running; the newest commit deploys when it finishes.
• Ignored: not a push to your branch (a test delivery, a tag, another branch or repository), or Auto-deploy on push is off. The reason is shown under it.
• Refused: the push could not deploy now, for example while the server is being upgraded, the website is being moved, or many deployments started in the last few minutes. The reason is shown under it; push again or click Deploy now later.

GitHub, GitLab and Bitbucket send a test delivery when you add the webhook. It shows here as Ignored, which means the webhook works.

Turn it off or replace the webhook

• Turn off Auto-deploy on push to stop deploying on push. Deliveries are still listed.
• Click Replace webhook if the address or secret may have leaked. The old ones stop working at once; update the webhook on your Git provider with the new ones.
• Click Remove to delete the webhook from Netkeel, then delete it on your Git provider too.

A website restored after it was deleted, or after its server was lost, doesn’t keep its webhook. Once the repository is set up again, create a new one.

Deployment history

Deployment history lists every deploy with its commit, trigger (Manual, Push or Rollback), start time, duration and status. The current release shows Live; earlier successful ones show Succeeded, and ones that did not go live show Failed. Live, with a warning means the release went live but a step after the switch failed; open its log to see which.

• Click Log to read a deploy’s output.
• Click Roll back to this release to switch the website back to an earlier successful deploy whose release is still kept. Nothing is rebuilt and no migrations run. For an older release, deploy its commit again instead.

Environment variables

The Owner and Super admins can set environment variables under Environment variables once the repository is set up. They are written to .env in the shared folder of every release, build commands can read them, and they apply from the next deployment.

Saved values are never shown again. To keep a value, leave it empty when you edit the list. Names use capital letters, numbers and underscores, and don’t start with a number. Each value is one line. You can set up to 100 variables. A few names, such as PATH and HOME, are set by the server and can’t be changed.

Change settings or disconnect

Click Edit settings on the Repository card to change the branch, preset or any other field, then click Save settings.

Click Disconnect to stop deploying. The website keeps serving its current files. The deploy key is deleted from the server and the deployment history is removed from Netkeel. A Node.js website’s environment variables go back to Node.js app.

Tip

Pushing to the branch deploys only once you have set up push to deploy. Otherwise, deploys start when you click Deploy now.

Troubleshooting

When a deploy fails, its error is shown under Deployment history. Click Log next to it to read the full output, including Git’s and your build’s own messages.

“Could not fetch branch” or “Permission denied (publickey)”

The deploy fails with Could not fetch branch main; check the repository address, the branch and that the deploy key is added to the repository. The log usually shows one of these messages from Git:

• Permission denied (publickey): the repository doesn’t have this website’s deploy key.
• Repository not found: the repository address is wrong, or the key was added to a different repository.

To fix it:

1. Go to Hosting › Deployments and click Copy key on the Deploy key card.
2. Click Open the deploy key settings on GitHub (or GitLab, or Bitbucket). Check that the page is for the repository shown on the Repository card, not another one.
3. Check that the key listed there is the one on the Deploy key card. If it isn’t there, or is different, add the copied key.
4. Click Deploy now again.

On GitHub, a deploy key belongs to one repository, and GitHub won’t let you add a key that is already used on another repository. Each Netkeel website has its own key, so if two websites deploy the same repository, add both websites’ keys to it.

Branch not found

If the log shows couldn't find remote ref followed by the branch name, the branch doesn’t exist in the repository. Branch names are case sensitive. Click Edit settings, correct the Branch and click Save settings, or push the branch first.

Commit not found

Commit … was not found in the repository means the hash under Commit isn’t in the repository. Check that the commit is pushed, or leave Commit empty to deploy the latest commit of the branch.

A build command failed

A build command failed (exit 1): npm run build names the command that stopped the build. The website stays on the release it was on. Read the log to see why, run the same command on your computer, fix the problem in the repository, push it and deploy again.

A build that runs longer than 15 minutes, or runs out of memory, stops with The deploy stopped before it finished (time limit, memory limit or a crash).

The publish directory is not in the release

The publish directory dist is not in the release means the folder named under Publish directory doesn’t exist after the build. Check its name, and that a build command creates it.

Not enough free disk space

Not enough free disk space to unpack the release means the server’s disk is nearly full. Free up space or upgrade the server to a size with a bigger disk.

Laravel migrations can’t reach the database

If php artisan migrate failed says to use DB_HOST=localhost and DB_SOCKET=/run/mysqld/mysqld.sock, your DB_HOST is 127.0.0.1, which doesn’t work. Change it under Environment variables, or remove your DB_* variables so Netkeel adds the website’s own database settings. See Laravel.

A Node.js release did not pass its health check

The history shows the deploy as Failed with Not switched to: the previous release is still live. The log ends with the health check’s result and the app’s last output. See Node.js.

Setting up the repository failed

The Repository card shows why. A common reason is a releases or shared folder with files in it already in the website’s htdocs: rename or move it with the file manager. Then click Edit settings and Save settings to try again.

After restoring a website

A website restored after it was deleted, or after its server was lost, gets a new deploy key. The Repository card says Restored from a backup: save the settings to set Git deploy up again, then add the new deploy key to the repository. Click Edit settings, then Save settings, and add the new key from the Deploy key card.

Pushes don’t deploy

Check Recent deliveries under Push to deploy:

• Nothing is listed: your Git provider can’t reach Netkeel, or its webhook has the wrong address or secret. Open the webhook’s delivery log on your Git provider. A 404 answer means the address or the secret is wrong: click Replace webhook and paste the new address and secret into the webhook on your Git provider. On GitHub, the webhook must have a secret.
• Ignored, Auto-deploy on push is off: turn on Auto-deploy on push to your branch.
• Ignored, A push to …, not …: the push went to another branch. Push to the branch on the Repository card, or change the branch with Edit settings.
• Refused: read the reason under it, then push again or click Deploy now.

Submodules and large files

Git submodules are not fetched, and files stored with Git LFS are not downloaded. Commit what the website needs to the repository itself, or install it with your build commands, for example with Composer or npm.