GitHub with VPS Hosting via WHM & cPanel

Why Connect GitHub to Your VPS?

If you're running a VPS with WHM and cPanel, you're likely hosting WordPress sites, PHP applications, or Node.js projects for clients. Manually uploading files via FTP is slow, error-prone, and impossible to roll back. By connecting GitHub to your VPS, you get:

• Version control — every change is tracked. Roll back to any previous version in seconds.
• Automated deployments — push to main and your server updates automatically. No FTP, no SSH-ing in to pull.
• Team collaboration — multiple developers can work on the same project without overwriting each other's files.
• CI/CD integration — run tests before deploying. If tests fail, the deploy is blocked.

This guide assumes you have a VPS with WHM/cPanel already provisioned. If you need help choosing a hosting provider, Hatty AI offers managed hosting solutions with WHM/cPanel pre-configured.

Step 1: Enable SSH Access in WHM

By default, cPanel accounts may not have SSH (shell) access enabled. You need to turn this on in WHM first.

1. Log into WHM at https://your-server-ip:2087.
2. Search for "Manage Shell Access" in the WHM search bar.
3. Find the cPanel account you want to enable SSH for.
4. Change the shell from Disabled to Normal Shell (/bin/bash).
5. Click "Save".

Step 2: Generate SSH Keys on Your Server

SSH keys provide passwordless, secure authentication between your server and GitHub.

1. SSH into your server: ssh cpaneluser@your-server-ip
2. Generate a new SSH key pair:

ssh-keygen -t ed25519 -C "deploy@yourdomain.com"
# Press Enter to accept default path (~/.ssh/id_ed25519)
# Leave passphrase empty for automated deployments

3. Display your public key:

cat ~/.ssh/id_ed25519.pub

Copy the entire output — you'll add this to GitHub in the next step.

Step 3: Add the SSH Key to GitHub

There are two places you can add SSH keys in GitHub, and the choice matters:

Adding a Deploy Key (Recommended for Production)

1. Go to your repo on GitHub → Settings → Deploy keys.
2. Click "Add deploy key".
3. Title: VPS Production - yourdomain.com
4. Paste the public key from Step 2.
5. Check "Allow write access" only if the server needs to push (usually not needed).
6. Click "Add key".

Test the connection from your server:

ssh -T git@github.com
# Expected: "Hi username! You've successfully authenticated..."

Step 4: Clone Your Repo to the Server

Navigate to the directory where your site files live and clone the repository:

# Navigate to your document root
cd /home/cpaneluser/public_html

# If the directory has existing files, back them up first
mv public_html public_html_backup

# Clone the repo
git clone git@github.com:your-org/your-repo.git public_html

# Set proper ownership
chown -R cpaneluser:cpaneluser /home/cpaneluser/public_html

Step 5: Use cPanel Git Version Control (Alternative Method)

cPanel has a built-in Git Version Control feature that provides a GUI for managing repos. Here's how to use it:

1. Log into cPanel at https://yourdomain.com:2083.
2. Search for "Git Version Control" in the cPanel search bar.
3. Click "Create".
4. Toggle "Clone a Repository" on.
5. Clone URL: git@github.com:your-org/your-repo.git
6. Repository Path: /home/cpaneluser/public_html
7. Repository Name: your project name.
8. Click "Create".

Setting Up the .cpanel.yml Deploy File

cPanel uses a .cpanel.yml file in your repo root to define deployment tasks. When you pull or push to the cPanel-managed repo, these tasks run automatically:

# .cpanel.yml
---
deployment:
  tasks:
    - export DEPLOYPATH=/home/cpaneluser/public_html
    - /bin/cp -R * $DEPLOYPATH/
    - cd $DEPLOYPATH && npm ci --production 2>/dev/null || true
    - cd $DEPLOYPATH && npm run build 2>/dev/null || true

Step 6: Automate Deploys with GitHub Actions

The most powerful approach combines GitHub Actions (CI/CD) with SSH deployment to your VPS. When you push to main, GitHub Actions runs your tests, builds the project, and deploys it to your server — all automatically.

If you haven't set up GitHub Actions yet, read our GitHub Account Types & CI/CD Guide first — it covers workflow files, secrets, and branch protection in detail.

The Deployment Workflow

# .github/workflows/deploy-to-vps.yml
name: Deploy to VPS

on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm test

  deploy:
    needs: test
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4

      - name: Deploy via SSH
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.VPS_HOST }}
          username: ${{ secrets.VPS_USER }}
          key: ${{ secrets.VPS_SSH_KEY }}
          port: ${{ secrets.VPS_PORT }}
          script: |
            cd /home/cpaneluser/public_html
            git fetch origin main
            git reset --hard origin/main
            npm ci --production
            npm run build

      - name: Verify Deployment
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.VPS_HOST }}
          username: ${{ secrets.VPS_USER }}
          key: ${{ secrets.VPS_SSH_KEY }}
          port: ${{ secrets.VPS_PORT }}
          script: |
            curl -s -o /dev/null -w "%{http_code}" https://yourdomain.com | grep -q "200"

GitHub Secrets You Need

Step 7: Set Up Webhooks for Instant Deploys

An alternative to GitHub Actions is using GitHub Webhooks to trigger a deploy script on your server whenever code is pushed:

1. Create a deploy script on your server:

#!/bin/bash
# /home/cpaneluser/deploy.sh
cd /home/cpaneluser/public_html
git fetch origin main
git reset --hard origin/main
npm ci --production 2>/dev/null
npm run build 2>/dev/null
echo "Deploy completed at $(date)" >> /home/cpaneluser/deploy.log

2. Create a simple PHP webhook receiver:

<?php
// /home/cpaneluser/public_html/webhook.php
$secret = getenv('WEBHOOK_SECRET');
$signature = $_SERVER['HTTP_X_HUB_SIGNATURE_256'] ?? '';
$payload = file_get_contents('php://input');

if (hash_equals('sha256=' . hash_hmac('sha256', $payload, $secret), $signature)) {
    exec('/home/cpaneluser/deploy.sh > /dev/null 2>&1 &');
    http_response_code(200);
    echo 'Deploy triggered';
} else {
    http_response_code(403);
    echo 'Invalid signature';
}
?>

3. In GitHub: repo → Settings → Webhooks → Add webhook.
4. Payload URL: https://yourdomain.com/webhook.php
5. Content type: application/json
6. Secret: a secure random string (add to your server as an environment variable).
7. Events: select "Just the push event".

Troubleshooting Common Issues

Security Checklist for GitHub + VPS Deployments

• ✅ Use deploy keys (repo-scoped) instead of account-wide SSH keys on production servers.
• ✅ Store all credentials in GitHub Secrets, never in code.
• ✅ Use a dedicated deploy user with minimal permissions — not root.
• ✅ Enable 2FA on your GitHub account and all WHM/cPanel accounts.
• ✅ Restrict SSH access to specific IP addresses via CSF or WHM Host Access Control.
• ✅ Rotate SSH keys at least annually.
• ✅ Keep .git directory outside your public document root, or block access via .htaccess.
• ✅ Use webhook secrets with HMAC signature verification.

Related: GitHub Account Types & CI/CD Guide · Managed IT Services · Essential Cybersecurity Practices