How to Deploy a Web Application on Ubuntu Server Using GitHub

Deploying your web applications directly from GitHub to an Ubuntu Linux Virtual Private Server (VPS) is the standard workflow for modern developers and engineering teams. Using Git version control streamlines updates, ensures code integrity, and eliminates slow, error-prone manual file uploads via FTP.

Whether you are deploying a frontend Single Page Application (React, Vue, HTML/CSS), a Node.js API, Python Django/Flask, or a PHP application on Ubuntu 26.04 LTS, Ubuntu 24.04 LTS, Ubuntu 22.04 LTS, or Ubuntu 20.04 LTS, setting up GitHub deployment can be done in two distinct ways:

• Method 1: Manual Git Deployment (Pull-Based) – Cloning your repository using secure GitHub Deploy Keys and running manual git pull updates over SSH.
• Method 2: Automated CI/CD Deployment via GitHub Actions (Push-Based) – Automatically deploying code updates to your Ubuntu server with zero downtime every time you push to your main branch.

In this comprehensive guide, we will walk you through both manual and automated GitHub deployment workflows step-by-step.

Prerequisites

• An active Linux VPS running Ubuntu (26.04, 24.04, 22.04, or 20.04 LTS).
• SSH access with sudo privileges (see How to Log in and Access Ubuntu Server via SSH and How to Create a Sudo User on Ubuntu).
• A GitHub account with a repository containing your web application code (Public or Private).
• Nginx web server installed and UFW firewall configured (see How to Set Up Nginx on Ubuntu Server and How to Configure UFW Firewall on Ubuntu).
• A domain name pointing to your VPS IP with SSL enabled (see How to Install Let's Encrypt SSL on Ubuntu Server).
• Note for DirectAdmin users: If you are using shared hosting with DirectAdmin instead of an Ubuntu VPS, refer to our guide on How to Deploy a Website in DirectAdmin Using Git.

Step 1: Install Git and Generate a GitHub Deploy Key on Ubuntu

To allow your Ubuntu server to securely clone and pull code from private GitHub repositories without storing your personal GitHub password, we configure a read-only GitHub Deploy Key.

1. Log in to your Ubuntu server via SSH and ensure Git is installed:

   sudo apt update && sudo apt install git -y

2. Generate a dedicated SSH key pair on your Ubuntu server:

   ssh-keygen -t ed25519 -C "ubuntu-vps-deploy-key"

   Press ENTER to accept the default file location (~/.ssh/id_ed25519) and leave the passphrase empty for automated access.

3. Display and copy your server’s public key:

   cat ~/.ssh/id_ed25519.pub

4. Open your web browser, navigate to your GitHub repository, and go to Settings > Deploy Keys > Add deploy key.
5. Give it a title (e.g. Aveshost Ubuntu VPS), paste the copied key into the Key box, and click Add key (leave "Allow write access" unchecked for maximum security).
6. Verify the connection from your Ubuntu terminal:

   ssh -T [email protected]

   Type yes when prompted. You will see: "Hi username/repo! You've successfully authenticated".

Method 1: Manual Deployment via Git Pull

Step 1: Clone Your Repository

Navigate to your web root directory (e.g. /var/www/) and clone your application using the SSH URL:

# Create directory if needed
sudo mkdir -p /var/www/my-app
sudo chown -R $USER:$USER /var/www/my-app

# Clone your repository
git clone [email protected]:username/my-web-app.git /var/www/my-app

Step 2: Install Dependencies & Build

• For Node.js / React / Vue Apps:

  cd /var/www/my-app
  npm install
  npm run build

• For Python (Django/Flask) Apps:

  cd /var/www/my-app
  python3 -m venv venv
  source venv/bin/activate
  pip install -r requirements.txt

• For PHP / Laravel Apps:

  cd /var/www/my-app
  composer install --no-dev --optimize-autoloader

Step 3: Deploying Future Updates Manually

Whenever you push changes to GitHub, connect to your server and run:

cd /var/www/my-app
git pull origin main
# Rebuild or restart your service (e.g. pm2 restart app OR sudo systemctl restart gunicorn)

Method 2: Automated CI/CD Deployment via GitHub Actions (Recommended)

With GitHub Actions, you can configure an automated deployment pipeline that logs into your Ubuntu VPS over SSH and updates your application automatically every time you commit to the main branch.

Step 1: Set Up an SSH Deployment Key for GitHub Actions

1. On your local computer (or server), generate a new key pair specifically for GitHub Actions:

   ssh-keygen -t ed25519 -f ~/.ssh/github_action_key -C "github-actions-deploy"

2. Append the public key (github_action_key.pub) to your server user’s ~/.ssh/authorized_keys file:

   cat ~/.ssh/github_action_key.pub | ssh username@YOUR_SERVER_IP "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"

Step 2: Add Secrets to Your GitHub Repository

1. In your GitHub repository, go to Settings > Secrets and variables > Actions > click New repository secret.
2. Add the following 4 secrets:

   Secret Name	Value
   HOST	Your VPS public IP address (e.g. 107.178.111.179)
   USERNAME	Your server sudo username (e.g. sammy or ubuntu)
   SSH_KEY	The entire private key content of github_action_key
   PORT	22 (or your custom SSH port)

Step 3: Create the GitHub Actions Workflow File

In your local repository, create a workflow file at .github/workflows/deploy.yml:

name: Deploy to Ubuntu VPS

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Execute Remote SSH Commands
        uses: appleboy/[email protected]
        with:
          host: ${{ secrets.HOST }}
          username: ${{ secrets.USERNAME }}
          key: ${{ secrets.SSH_KEY }}
          port: ${{ secrets.PORT }}
          script: |
            cd /var/www/my-app
            git pull origin main
            
            # Example for Node.js / React:
            npm install
            npm run build
            # pm2 restart all
            
            # Example for Python:
            # source venv/bin/activate
            # pip install -r requirements.txt
            # sudo systemctl restart gunicorn
            
            # Reload web server
            sudo systemctl reload nginx

Commit and push this file to GitHub:

git add .github/workflows/deploy.yml
git commit -m "Add automated GitHub Actions deployment"
git push origin main

Every time you push code to main, GitHub Actions will trigger, connect to your Ubuntu server over SSH, pull the latest code, install dependencies, rebuild assets, and reload Nginx automatically!

Step 4: Configuring Nginx for Your Deployed App

Create or update your Nginx server block to point to your application:

server {
    listen 80;
    listen [::]:80;
    server_name domain.com www.domain.com;

    # For static frontend apps (React/Vue/HTML):
    root /var/www/my-app/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # For Node.js / Python API backends (e.g. Port 3000/5000):
    # location / {
    #     proxy_pass http://127.0.0.1:3000;
    #     proxy_http_version 1.1;
    #     proxy_set_header Upgrade $http_upgrade;
    #     proxy_set_header Connection 'upgrade';
    #     proxy_set_header Host $host;
    #     proxy_cache_bypass $http_upgrade;
    # }

    access_log /var/log/nginx/my-app.access.log;
    error_log /var/log/nginx/my-app.error.log;
}

Test syntax and reload Nginx: sudo nginx -t && sudo systemctl reload nginx.

Security Best Practices for GitHub Deployments

• Never commit .env secrets to Git: Keep your production environment variables (database passwords, API secret keys) in a dedicated .env file directly on the Ubuntu server and add .env to your .gitignore file.
• Use Read-Only Deploy Keys: Deploy keys should always have read-only access so that a compromised server cannot alter code in your GitHub repository.
• Keep Sudo Privileges Minimal: Allow your deploy user to reload Nginx without prompting for a password by adding sammy ALL=(ALL) NOPASSWD: /bin/systemctl reload nginx to /etc/sudoers.d/deploy.

Frequently Asked Questions & Troubleshooting

Q: Why does git pull fail with "Host key verification failed"?
A: Run ssh-keyscan -H github.com >> ~/.ssh/known_hosts on your server to add GitHub’s public RSA/ED25519 key to your known hosts list.

Q: Why does GitHub Actions fail with "Permission denied (publickey)"?
A: Check that the private key added to GitHub Secrets matches the public key saved in ~/.ssh/authorized_keys on your server, and ensure file permissions are 700 for ~/.ssh and 600 for authorized_keys.

Q: How can I roll back to a previous commit if a deployment breaks?
A: In your server directory, run git log --oneline to find the previous commit hash, then run git checkout <commit-hash> (or revert the commit in GitHub and push to main).

Need Further Assistance?

If you encounter any issues setting up Git deploy keys, building automated CI/CD pipelines with GitHub Actions, or configuring web servers on your Ubuntu VPS, our technical support team is available 24/7. Feel free to submit a support ticket through your client area for expert assistance.