Deploy from GitHub or GitLab with Plesk
Connect a GitHub or GitLab repository to Plesk, deploy your site manually or automatically on every push with a webhook, and fix the most frequent errors.
On this page
Your values
Enter them once and the commands in this guide update.
This guide shows you how to connect a GitHub or GitLab repository to your Plesk site. Once the setup is complete, a simple git push can update your site.
Here is how it works: you push your changes to GitHub or GitLab, Plesk pulls the new commits, then copies the files from the active branch to your site's folder.
Prerequisites
- Access to your Plesk panel (see Connect to Plesk interface).
- A GitHub or GitLab repository containing your site.
- Administrator rights on the repository to add a key and a webhook. On GitLab, you need the Maintainer or Owner role.
This guide uses httpdocs, the usual folder for the main domain. For an additional domain, the folder may be different: check the Document root under Hosting & DNS > Hosting.
Step 1: prepare the repository
The contents of the repository root are copied to the target folder, /httpdocs by default. An index.html file at the root of the repository therefore becomes httpdocs/index.html.
Never commit your secrets or generated files. Here is an example .gitignore:
.env
node_modules/
vendor/
*.logFiles ignored by Git are not deployed. A .env file must therefore be created directly on the server.
Step 2: add the repository in Plesk
- Go to Websites & Domains and find your domain.
- Click Git. If a repository already exists, click Add Repository.
- Select Remote git hosting like GitHub or BitBucket. This option also works for GitLab.
- In the Remote Git repository field, enter your repository address.
| Repository type | Address format |
|---|---|
| Public | https://github.com/your-account/my-site.git |
| Private, GitHub | git@github.com:your-account/my-site.git |
| Private, GitLab | git@gitlab.com:your-account/my-site.git |
For a private repository, the SSH format is recommended: Plesk then generates a key and displays the SSH public key field. Do not confirm yet: go to step 3.
Step 3: allow Plesk to read a private repository
Copy the contents of the SSH public key field, then add it as a deploy key.
On GitHub:
- Open the repository, then Settings > Deploy keys.
- Click Add deploy key.
- Give the key a name in Title, for example
Plesk, and paste the key into Key. - Leave Allow write access unchecked: Plesk only needs to read the repository.
- Click Add key.
On GitLab:
- Open the project, then Settings > Repository.
- Expand Deploy keys and select Add new key.
- Give the key a name and paste it.
- Leave Grant write permissions to this key unchecked, then save.
Step 4: choose the deployment mode
Back in Plesk, in the Your Website section:
-
Choose the Deployment Mode:
Mode Effect Automatic deployment Pulled commits are published immediately Manual deployment Commits are pulled, but only published when you request it No deployment (repository hosting) Nothing is published -
Check the target directory. Keep
/httpdocsfor a standard site. -
Click OK. Plesk then clones the repository.
For a production site, manual mode is the safer choice until your process is proven: in automatic mode, any mistake pushed to the active branch goes live immediately.
Step 5: select the branch and deploy
- On the Git page, click Change branch and path.
- Under Branch, select your production branch, for example
main, then confirm. - Click Pull Updates.
- In manual mode, click Deploy from Repository (or Deploy).
Only the active branch is deployed.
Step 6: automate with a webhook
Without a webhook, Plesk does not know that a new commit exists and you have to click Pull Updates. The webhook notifies it on every git push.
In Plesk, click Repository Settings and copy the Webhook URL. Treat it as a secret: anyone who knows it can trigger a pull.
On GitHub:
- Open Settings > Webhooks, then click Add webhook.
- Paste the address into Payload URL.
- Under Content type, choose
application/json. - Keep sending the
pushevent only (Just the push event). - Check that Active is selected, then click Add webhook.
On GitLab:
- Open Settings > Webhooks, then select Add new webhook.
- Paste the address into URL.
- Under Trigger, select Push events.
- Leave Enable SSL verification on if the Plesk certificate is valid.
- Select Add webhook.
Step 7: run actions after deployment
Some projects need an action after the files are copied, such as restarting an application or clearing a cache.
- In Repository Settings, select Enable additional deploy actions.
- Enter one command per line.
For example, to restart a Node.js application whose folder is httpdocs:
cd httpdocs
mkdir -p tmp
touch tmp/restart.txtTo install the dependencies and build the same project, replacing 24 with the Node.js version you use:
export PATH=/opt/plesk/node/24/bin:$PATH
cd httpdocs
npm ci
npm run build
mkdir -p tmp
touch tmp/restart.txtFor a Laravel project, see Host a Laravel site on Plesk.
Check the result
-
Change a visible file, then push the change:
Terminalgit add . git commit -m "Test deployment" git push origin main -
In Plesk, on the Git page, check that the latest commit shown is yours. Commit Logs shows the history.
-
Reload
https://your-domain.com/and check the change. -
Check the webhook delivery:
- GitHub: Settings > Webhooks, open the webhook, then Recent deliveries;
- GitLab: Settings > Webhooks, Edit, then Recent events. The Test > Push events button also lets you send a test.
Roll back to a previous version
Revert the faulty commit, then push the result:
git revert HEAD
git push origin mainA new deployment restores the files. If database migrations have been run, this operation does not undo them.
Troubleshooting
Permission denied (publickey)
The Plesk public key has not been added to the repository, or it was added to a different one. Copy it again from Plesk and check the list of deploy keys.
Key is already in use on GitHub
This deploy key is already associated with another repository. Remove it from that repository or add it to a dedicated GitHub account.
Repository not found or Authentication failed
The address is incorrect, the repository is private while you are using an HTTPS address without credentials, or the token has expired. Since a repository's address cannot be changed in Plesk, delete it with Remove Repository, then add it again. Files already published are kept.
Pushing does not trigger any update
Check the following, in this order:
- the commit was pushed to the active branch;
- the mode is not Manual deployment or No deployment;
- the webhook was received, in the GitHub or GitLab history.
The webhook fails with a certificate error
If the Plesk panel uses a self-signed certificate, the HTTPS connection may fail. In that case, Plesk recommends using http:// at the start of the webhook URL. Since the URL then travels unencrypted, only use this solution temporarily and report the problem to support.
GitLab says the webhook is disabled
GitLab temporarily disables a webhook after four consecutive failures, then permanently after forty. Fix the cause, then send a successful test to re-enable it.
Files have disappeared from the site
A file deleted from the repository is also deleted from the site during deployment. Store files uploaded by your users in a folder that is not under version control, and restore lost files from a backup.
The target directory is rejected
Two repositories on the same domain cannot share the same deployment folder. Choose a different target directory.
The old page is still displayed
An index.html file may take priority over your index.php, particularly the default page created by Plesk. Delete it from httpdocs if it is not part of your project, then clear your browser cache.
npm: command not found in deployment actions
The tools path is not loaded in this context. Add the line export PATH=/opt/plesk/node/24/bin:$PATH, adjusting the version. If the error persists, the environment is probably chrooted.