Deploying a Laravel application to a freshly created VPS can quickly become overwhelming. There are many ways to put a web application online, and it's easy to lose focus trying to build the "perfect" deployment workflow — only to end up with something hard to maintain.
In real projects, what matters most is a reliable, repeatable, and safe deployment process that lets you focus on writing code rather than manually pushing changes to servers.
In this article, I'll walk through a minimal yet production-ready CI/CD approach for deploying Laravel applications to a VPS (or EC2 instance) using GitHub Actions and SSH.
⚠️ The goal is not to cover every possible optimization, but to present a workflow that works well for real client projects and personal products.
💡 Not on a VPS yet? This guide focuses on automated deployment for servers where you have full root privileges. If you are stuck with Shared Hosting (cPanel) and don't have SSH access, check out my alternative guide: 👉 How to Deploy Laravel on Shared Hosting (No SSH Required)
Stack Used
To keep things concrete, this guide assumes the following setup:
- Ubuntu Server (20.04+)
- Laravel 12 with PHP 8.3
- Nginx + PHP-FPM
- MySQL
- GitHub Actions for CI/CD
This guide assumes basic familiarity with Linux and Laravel.
Step 1 — Installing Server Requirements
After connecting to your server via SSH, it's recommended not to work as root, but as a sudo-enabled user.
The key idea here is that this setup is done once. After the initial server preparation, deployments should not require installing system dependencies again.
# Update system list and upgrade packages
sudo apt update && sudo apt upgrade -y
# Install Nginx
sudo apt install nginx -y
# Install Mysql Server
sudo apt install mysql-server -y
# Install PHP and required Packages
sudo apt install php-cli php-fpm php-mysql php-xml php-mbstring php-curl unzip -y
# Install Composer
sudo curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer
# Install Node.js and NPM
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install -y nodejs
⚠️ Be careful to install a PHP version that matches your Laravel version requirements. Mismatches here are a common source of production issues.
Step 2 — Configuring Nginx for Laravel
We need to configure Nginx to point to the current/public directory (which we will create later via our CI/CD pipeline). Let's create configs:
sudo touch /etc/nginx/sites-available/laravel-app
server {
listen 80;
server_name your-domain.com;
# POINT TO 'current/public' FOR ATOMIC DEPLOYMENTS
root /var/www/laravel-app/current/public;
add_header X-Frame-Options "SAMEORIGIN";
add_header X-Content-Type-Options "nosniff";
index index.php;
charset utf-8;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location = /favicon.ico { access_log off; log_not_found off; }
location = /robots.txt { access_log off; log_not_found off; }
error_page 404 /index.php;
location ~ \.php$ {
fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
include fastcgi_params;
}
location ~ /\.(?!well-known).* {
deny all;
}
}
Then, we enable the configuration and ensure it is working:
sudo ln -s /etc/nginx/sites-available/laravel-app /etc/nginx/sites-enabled/
sudo unlink /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl restart nginx
⚠️ Replace your-domain.com with your actual domain.
Step 3 — Set up MySQL server and create a database
Let's execute the MySQL security script:
# Secure MySQL (set root password, remove anonymous users)
sudo mysql_secure_installation
# Log in to MySQL
sudo mysql -u root -p
Then, we create the application database that we will use:
CREATE DATABASE laravel_db;
CREATE USER 'laravel_user'@'localhost' IDENTIFIED BY 'your-strong-password';
GRANT ALL PRIVILEGES ON laravel_db.* TO 'laravel_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;
Once created, we should add the database access in the production .env
⚠️ The .env is never committed to Git and is created only once on the server. CI/CD pipelines should never modify it.
Step 4 — Initializing the Application on the Server
Before automation, we need to set up the folder structure. We will create a "shared" structure so that logs and uploads persist between deployments.
# 1. Create the main directory
sudo mkdir -p /var/www/laravel-app
sudo chown -R $USER:www-data /var/www/laravel-app
# 2. Setup the persistent folders
cd /var/www/laravel-app
mkdir -p shared/storage/framework/{cache/data,sessions,views}
# 3. Create the .env file
nano shared/.env
# (Paste your production env content here)
# 4. Set permissions ONE TIME
sudo chown -R $USER:www-data /var/www/laravel-app
sudo chmod -R 775 shared/storage
Step 5 — CI/CD Strategy with GitHub Actions
Instead of running Composer and NPM commands directly on the server, the deployment workflow follows a build-then-deploy strategy:
Why build in CI instead of the server?
- Faster deployments
- More predictable results
- Fewer production dependencies
- Easier debugging
- Reduced server load
In this approach:
- GitHub Actions installs PHP and Node
- Composer dependencies are installed
- Frontend assets are built
- A clean release artifact is generated
- The artifact is deployed to the server via SSH
- A new release directory is created
- The
currentsymlink is updated atomically
The server becomes a stable runtime environment, not a build machine.
Create .github/workflows/deploy.yml in your Laravel project:
name: Deploy Laravel to VPS
on:
push:
branches: [ main ]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
# 1️⃣ Checkout Code
- name: Checkout repository
uses: actions/checkout@v4
# 2️⃣ Setup PHP
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: 8.3
extensions: mbstring, xml, ctype, iconv, intl, pdo_mysql
# 3️⃣ Install Backend Dependencies
- name: Install Composer dependencies
run: |
composer install --no-dev --prefer-dist --optimize-autoloader
# 4️⃣ Build Frontend Assets
- name: Setup Node & Build
uses: actions/setup-node@v4
with:
node-version: 20
- run: |
npm ci
npm run build
# 5️⃣ Prepare Files for Transfer
- name: Archive application
run: |
tar --exclude='./storage' \
--exclude='./.git' \
--exclude='./node_modules' \
--exclude='./tests' \
-czf /tmp/release.tar.gz .
# 2. Move it back to the workspace
mv /tmp/release.tar.gz .
# 6️⃣ Upload to Server
- name: Upload artifact via SCP
uses: appleboy/scp-action@master
with:
host: ${{ secrets.VPS_HOST }}
username: ${{ secrets.VPS_USERNAME }}
key: ${{ secrets.VPS_SSH_KEY }}
port: ${{ secrets.VPS_PORT || 22 }}
source: "release.tar.gz"
target: "/var/www/laravel-app"
# 7️⃣ Deploy on Server
- name: Execute Remote SSH Commands
uses: appleboy/ssh-action@master
with:
host: ${{ secrets.VPS_HOST }}
username: ${{ secrets.VPS_USERNAME }}
key: ${{ secrets.VPS_SSH_KEY }}
port: ${{ secrets.VPS_PORT || 22 }}
script: |
set -e
APP_DIR="/var/www/laravel-app"
RELEASE_ID=$(date +%Y%m%d%H%M%S)
RELEASE_PATH="$APP_DIR/releases/$RELEASE_ID"
# 1. Create new release directory
mkdir -p $RELEASE_PATH
# 2. Extract files
tar -xzf $APP_DIR/release.tar.gz -C $RELEASE_PATH
rm $APP_DIR/release.tar.gz
# 3. Link Shared Resources
ln -sfn $APP_DIR/shared/.env $RELEASE_PATH/.env
ln -sfn $APP_DIR/shared/storage $RELEASE_PATH/storage
# 4. Set Permissions
sudo chown -R $USER:www-data $RELEASE_PATH
# Ensure group write access for cache (so webserver can write to it)
sudo chmod -R 775 $RELEASE_PATH/bootstrap/cache
# 5. Run Migrations & Optimize
cd $RELEASE_PATH
php artisan migrate --force
php artisan optimize
# 6. Atomic Switch (Zero Downtime)
ln -sfn $RELEASE_PATH $APP_DIR/current
# 7. Reload PHP-FPM (Ensure this matches your server version!)
sudo systemctl reload php8.3-fpm
# 8. Cleanup old releases (keep latest 5)
cd $APP_DIR/releases
ls -t | tail -n +6 | xargs -r rm -rf
echo "🚀 Deployment $RELEASE_ID success!"
In your GitHub repository:
- Go to Settings → Secrets and variables → Actions
- Add these secrets:
VPS_HOST: Your VPS IP address
VPS_USERNAME: SSH username
VPS_SSH_KEY: Private SSH key
VPS_PORT: SSH port (default: 22)
Step 6 — Release-Based Deployment Flow
Each deployment creates a new release directory:
/var/www/laravel-app/releases/20260210151258
Shared directories such as storage and bootstrap/cache are symlinked into each release.
Once everything is ready:
- Database migrations are executed with
--force
- Caches are optimized
- The
currentsymlink is switched to the new release
⚡ Because the symlink update is atomic, users rarely notice downtime.
Troubleshooting Common Issues
500 Internal Server Error
Most commonly caused by:
- Incorrect file permissions
- Missing PHP extensions
- Wrong PHP-FPM socket version
- Broken symlink paths
Check that storage/ and bootstrap/cache/ are writable.
Blank Page After Deployment
Often caused by:
- Incorrect Nginx root path
- Missing
.env
- Application key not generated
Make sure:
APP_ENV=production
APP_DEBUG=false
SSH Action Fails
Usually due to:
- Incorrect private key format
- Wrong SSH username
- Server firewall rules
Test SSH access manually before debugging CI.
Final Thoughts
This setup gives you a professional, automated pipeline. You push to main, and GitHub Actions handles the rest — running tests, building assets, and switching the live site without dropping connections.
Happy Deploying! 🚀
🔗 Stay Connected
Follow me for more Laravel tutorials, dev tips, deployment workflows and solving real-world production headaches.
- Follow me on LinkedIn
- Follow me here on Medium and join my mailing list for more in-depth content and tutorials!
Found this article useful?
🙏 Show your support by clapping 👏, subscribing 🔔, sharing to social networks
Tags: Laravel, VPS, GitHub Actions, CI/CD, Nginx
Step 1 — Installing Server Requirements
After connecting to your server via SSH, it's recommended not to work as root, but as a sudo-enabled user.
The key idea here is that this setup is done once. After the initial server preparation, deployments should not require installing system dependencies again.
# Update system list and upgrade packages
sudo apt update && sudo apt upgrade -y
# Install Nginx
sudo apt install nginx -y
# Install Mysql Server
sudo apt install mysql-server -y
# Install PHP and required Packages
sudo apt install php-cli php-fpm php-mysql php-xml php-mbstring php-curl unzip -y
# Install Composer
sudo curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer
# Install Node.js and NPM
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install -y nodejs
⚠️ Be careful to install a PHP version that matches your Laravel version requirements. Mismatches here are a common source of production issues.
Step 2 — Configuring Nginx for Laravel
We need to configure Nginx to point to the current/public directory (which we will create later via our CI/CD pipeline). Let's create configs:
sudo touch /etc/nginx/sites-available/laravel-app
server {
listen 80;
server_name your-domain.com;
# POINT TO 'current/public' FOR ATOMIC DEPLOYMENTS
root /var/www/laravel-app/current/public;
add_header X-Frame-Options "SAMEORIGIN";
add_header X-Content-Type-Options "nosniff";
index index.php;
charset utf-8;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location = /favicon.ico { access_log off; log_not_found off; }
location = /robots.txt { access_log off; log_not_found off; }
error_page 404 /index.php;
location ~ \.php$ {
fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
include fastcgi_params;
}
location ~ /\.(?!well-known).* {
deny all;
}
}
Then, we enable the configuration and ensure it is working:
sudo ln -s /etc/nginx/sites-available/laravel-app /etc/nginx/sites-enabled/
sudo unlink /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl restart nginx
⚠️ Replace your-domain.com with your actual domain.
Step 3 — Set up MySQL server and create a database
Let's execute the MySQL security script:
# Secure MySQL (set root password, remove anonymous users)
sudo mysql_secure_installation
# Log in to MySQL
sudo mysql -u root -p
Then, we create the application database that we will use:
CREATE DATABASE laravel_db;
CREATE USER 'laravel_user'@'localhost' IDENTIFIED BY 'your-strong-password';
GRANT ALL PRIVILEGES ON laravel_db.* TO 'laravel_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;
Once created, we should add the database access in the production .env
⚠️ The .env is never committed to Git and is created only once on the server. CI/CD pipelines should never modify it.
Step 4 — Initializing the Application on the Server
Before automation, we need to set up the folder structure. We will create a "shared" structure so that logs and uploads persist between deployments.
# 1. Create the main directory
sudo mkdir -p /var/www/laravel-app
sudo chown -R $USER:www-data /var/www/laravel-app
# 2. Setup the persistent folders
cd /var/www/laravel-app
mkdir -p shared/storage/framework/{cache/data,sessions,views}
# 3. Create the .env file
nano shared/.env
# (Paste your production env content here)
# 4. Set permissions ONE TIME
sudo chown -R $USER:www-data /var/www/laravel-app
sudo chmod -R 775 shared/storage
Step 5 — CI/CD Strategy with GitHub Actions
Instead of running Composer and NPM commands directly on the server, the deployment workflow follows a build-then-deploy strategy:
Why build in CI instead of the server?
- Faster deployments
- More predictable results
- Fewer production dependencies
- Easier debugging
- Reduced server load
In this approach:
- GitHub Actions installs PHP and Node
- Composer dependencies are installed
- Frontend assets are built
- A clean release artifact is generated
- The artifact is deployed to the server via SSH
- A new release directory is created
- The
currentsymlink is updated atomically
The server becomes a stable runtime environment, not a build machine.
Create .github/workflows/deploy.yml in your Laravel project:
name: Deploy Laravel to VPS
on:
push:
branches: [ main ]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
# 1️⃣ Checkout Code
- name: Checkout repository
uses: actions/checkout@v4
# 2️⃣ Setup PHP
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: 8.3
extensions: mbstring, xml, ctype, iconv, intl, pdo_mysql
# 3️⃣ Install Backend Dependencies
- name: Install Composer dependencies
run: |
composer install --no-dev --prefer-dist --optimize-autoloader
# 4️⃣ Build Frontend Assets
- name: Setup Node & Build
uses: actions/setup-node@v4
with:
node-version: 20
- run: |
npm ci
npm run build
# 5️⃣ Prepare Files for Transfer
- name: Archive application
run: |
tar --exclude='./storage' \
--exclude='./.git' \
--exclude='./node_modules' \
--exclude='./tests' \
-czf /tmp/release.tar.gz .
# 2. Move it back to the workspace
mv /tmp/release.tar.gz .
# 6️⃣ Upload to Server
- name: Upload artifact via SCP
uses: appleboy/scp-action@master
with:
host: ${{ secrets.VPS_HOST }}
username: ${{ secrets.VPS_USERNAME }}
key: ${{ secrets.VPS_SSH_KEY }}
port: ${{ secrets.VPS_PORT || 22 }}
source: "release.tar.gz"
target: "/var/www/laravel-app"
# 7️⃣ Deploy on Server
- name: Execute Remote SSH Commands
uses: appleboy/ssh-action@master
with:
host: ${{ secrets.VPS_HOST }}
username: ${{ secrets.VPS_USERNAME }}
key: ${{ secrets.VPS_SSH_KEY }}
port: ${{ secrets.VPS_PORT || 22 }}
script: |
set -e
APP_DIR="/var/www/laravel-app"
RELEASE_ID=$(date +%Y%m%d%H%M%S)
RELEASE_PATH="$APP_DIR/releases/$RELEASE_ID"
# 1. Create new release directory
mkdir -p $RELEASE_PATH
# 2. Extract files
tar -xzf $APP_DIR/release.tar.gz -C $RELEASE_PATH
rm $APP_DIR/release.tar.gz
# 3. Link Shared Resources
ln -sfn $APP_DIR/shared/.env $RELEASE_PATH/.env
ln -sfn $APP_DIR/shared/storage $RELEASE_PATH/storage
# 4. Set Permissions
sudo chown -R $USER:www-data $RELEASE_PATH
# Ensure group write access for cache (so webserver can write to it)
sudo chmod -R 775 $RELEASE_PATH/bootstrap/cache
# 5. Run Migrations & Optimize
cd $RELEASE_PATH
php artisan migrate --force
php artisan optimize
# 6. Atomic Switch (Zero Downtime)
ln -sfn $RELEASE_PATH $APP_DIR/current
# 7. Reload PHP-FPM (Ensure this matches your server version!)
sudo systemctl reload php8.3-fpm
# 8. Cleanup old releases (keep latest 5)
cd $APP_DIR/releases
ls -t | tail -n +6 | xargs -r rm -rf
echo "🚀 Deployment $RELEASE_ID success!"
In your GitHub repository:
- Go to Settings → Secrets and variables → Actions
- Add these secrets:
VPS_HOST: Your VPS IP address
VPS_USERNAME: SSH username
VPS_SSH_KEY: Private SSH key
VPS_PORT: SSH port (default: 22)
Step 6 — Release-Based Deployment Flow
Each deployment creates a new release directory:
/var/www/laravel-app/releases/20260210151258
Shared directories such as storage and bootstrap/cache are symlinked into each release.
Once everything is ready:
- Database migrations are executed with
--force
- Caches are optimized
- The
currentsymlink is switched to the new release
⚡ Because the symlink update is atomic, users rarely notice downtime.
Troubleshooting Common Issues
500 Internal Server Error
Most commonly caused by:
- Incorrect file permissions
- Missing PHP extensions
- Wrong PHP-FPM socket version
- Broken symlink paths
Check that storage/ and bootstrap/cache/ are writable.
Blank Page After Deployment
Often caused by:
- Incorrect Nginx root path
- Missing
.env
- Application key not generated
Make sure:
APP_ENV=production
APP_DEBUG=false
SSH Action Fails
Usually due to:
- Incorrect private key format
- Wrong SSH username
- Server firewall rules
Test SSH access manually before debugging CI.
Final Thoughts
This setup gives you a professional, automated pipeline. You push to main, and GitHub Actions handles the rest — running tests, building assets, and switching the live site without dropping connections.
Happy Deploying! 🚀
🔗 Stay Connected
Follow me for more Laravel tutorials, dev tips, deployment workflows and solving real-world production headaches.
- Follow me on LinkedIn
- Follow me here on Medium and join my mailing list for more in-depth content and tutorials!
Found this article useful?
🙏 Show your support by clapping 👏, subscribing 🔔, sharing to social networks
Tags: Laravel, VPS, GitHub Actions, CI/CD, Nginx
Step 1 — Installing Server Requirements
After connecting to your server via SSH, it's recommended not to work as root, but as a sudo-enabled user.
The key idea here is that this setup is done once. After the initial server preparation, deployments should not require installing system dependencies again.
# Update system list and upgrade packages
sudo apt update && sudo apt upgrade -y
# Install Nginx
sudo apt install nginx -y
# Install Mysql Server
sudo apt install mysql-server -y
# Install PHP and required Packages
sudo apt install php-cli php-fpm php-mysql php-xml php-mbstring php-curl unzip -y
# Install Composer
sudo curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer
# Install Node.js and NPM
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install -y nodejs
⚠️ Be careful to install a PHP version that matches your Laravel version requirements. Mismatches here are a common source of production issues.
Step 2 — Configuring Nginx for Laravel
We need to configure Nginx to point to the current/public directory (which we will create later via our CI/CD pipeline). Let's create configs:
sudo touch /etc/nginx/sites-available/laravel-app
server {
listen 80;
server_name your-domain.com;
# POINT TO 'current/public' FOR ATOMIC DEPLOYMENTS
root /var/www/laravel-app/current/public;
add_header X-Frame-Options "SAMEORIGIN";
add_header X-Content-Type-Options "nosniff";
index index.php;
charset utf-8;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location = /favicon.ico { access_log off; log_not_found off; }
location = /robots.txt { access_log off; log_not_found off; }
error_page 404 /index.php;
location ~ \.php$ {
fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
include fastcgi_params;
}
location ~ /\.(?!well-known).* {
deny all;
}
}
Then, we enable the configuration and ensure it is working:
sudo ln -s /etc/nginx/sites-available/laravel-app /etc/nginx/sites-enabled/
sudo unlink /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl restart nginx
⚠️ Replace your-domain.com with your actual domain.
Step 3 — Set up MySQL server and create a database
Let's execute the MySQL security script:
# Secure MySQL (set root password, remove anonymous users)
sudo mysql_secure_installation
# Log in to MySQL
sudo mysql -u root -p
Then, we create the application database that we will use:
CREATE DATABASE laravel_db;
CREATE USER 'laravel_user'@'localhost' IDENTIFIED BY 'your-strong-password';
GRANT ALL PRIVILEGES ON laravel_db.* TO 'laravel_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;
Once created, we should add the database access in the production .env
⚠️ The .env is never committed to Git and is created only once on the server. CI/CD pipelines should never modify it.
Step 4 — Initializing the Application on the Server
Before automation, we need to set up the folder structure. We will create a "shared" structure so that logs and uploads persist between deployments.
# 1. Create the main directory
sudo mkdir -p /var/www/laravel-app
sudo chown -R $USER:www-data /var/www/laravel-app
# 2. Setup the persistent folders
cd /var/www/laravel-app
mkdir -p shared/storage/framework/{cache/data,sessions,views}
# 3. Create the .env file
nano shared/.env
# (Paste your production env content here)
# 4. Set permissions ONE TIME
sudo chown -R $USER:www-data /var/www/laravel-app
sudo chmod -R 775 shared/storage
Step 5 — CI/CD Strategy with GitHub Actions
Instead of running Composer and NPM commands directly on the server, the deployment workflow follows a build-then-deploy strategy:
Why build in CI instead of the server?
- Faster deployments
- More predictable results
- Fewer production dependencies
- Easier debugging
- Reduced server load
In this approach:
- GitHub Actions installs PHP and Node
- Composer dependencies are installed
- Frontend assets are built
- A clean release artifact is generated
- The artifact is deployed to the server via SSH
- A new release directory is created
- The
currentsymlink is updated atomically
The server becomes a stable runtime environment, not a build machine.
Create .github/workflows/deploy.yml in your Laravel project:
name: Deploy Laravel to VPS
on:
push:
branches: [ main ]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
# 1️⃣ Checkout Code
- name: Checkout repository
uses: actions/checkout@v4
# 2️⃣ Setup PHP
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: 8.3
extensions: mbstring, xml, ctype, iconv, intl, pdo_mysql
# 3️⃣ Install Backend Dependencies
- name: Install Composer dependencies
run: |
composer install --no-dev --prefer-dist --optimize-autoloader
# 4️⃣ Build Frontend Assets
- name: Setup Node & Build
uses: actions/setup-node@v4
with:
node-version: 20
- run: |
npm ci
npm run build
# 5️⃣ Prepare Files for Transfer
- name: Archive application
run: |
tar --exclude='./storage' \
--exclude='./.git' \
--exclude='./node_modules' \
--exclude='./tests' \
-czf /tmp/release.tar.gz .
# 2. Move it back to the workspace
mv /tmp/release.tar.gz .
# 6️⃣ Upload to Server
- name: Upload artifact via SCP
uses: appleboy/scp-action@master
with:
host: ${{ secrets.VPS_HOST }}
username: ${{ secrets.VPS_USERNAME }}
key: ${{ secrets.VPS_SSH_KEY }}
port: ${{ secrets.VPS_PORT || 22 }}
source: "release.tar.gz"
target: "/var/www/laravel-app"
# 7️⃣ Deploy on Server
- name: Execute Remote SSH Commands
uses: appleboy/ssh-action@master
with:
host: ${{ secrets.VPS_HOST }}
username: ${{ secrets.VPS_USERNAME }}
key: ${{ secrets.VPS_SSH_KEY }}
port: ${{ secrets.VPS_PORT || 22 }}
script: |
set -e
APP_DIR="/var/www/laravel-app"
RELEASE_ID=$(date +%Y%m%d%H%M%S)
RELEASE_PATH="$APP_DIR/releases/$RELEASE_ID"
# 1. Create new release directory
mkdir -p $RELEASE_PATH
# 2. Extract files
tar -xzf $APP_DIR/release.tar.gz -C $RELEASE_PATH
rm $APP_DIR/release.tar.gz
# 3. Link Shared Resources
ln -sfn $APP_DIR/shared/.env $RELEASE_PATH/.env
ln -sfn $APP_DIR/shared/storage $RELEASE_PATH/storage
# 4. Set Permissions
sudo chown -R $USER:www-data $RELEASE_PATH
# Ensure group write access for cache (so webserver can write to it)
sudo chmod -R 775 $RELEASE_PATH/bootstrap/cache
# 5. Run Migrations & Optimize
cd $RELEASE_PATH
php artisan migrate --force
php artisan optimize
# 6. Atomic Switch (Zero Downtime)
ln -sfn $RELEASE_PATH $APP_DIR/current
# 7. Reload PHP-FPM (Ensure this matches your server version!)
sudo systemctl reload php8.3-fpm
# 8. Cleanup old releases (keep latest 5)
cd $APP_DIR/releases
ls -t | tail -n +6 | xargs -r rm -rf
echo "🚀 Deployment $RELEASE_ID success!"
In your GitHub repository:
- Go to Settings → Secrets and variables → Actions
- Add these secrets:
VPS_HOST: Your VPS IP address
VPS_USERNAME: SSH username
VPS_SSH_KEY: Private SSH key
VPS_PORT: SSH port (default: 22)
Step 6 — Release-Based Deployment Flow
Each deployment creates a new release directory:
/var/www/laravel-app/releases/20260210151258
Shared directories such as storage and bootstrap/cache are symlinked into each release.
Once everything is ready:
- Database migrations are executed with
--force
- Caches are optimized
- The
currentsymlink is switched to the new release
⚡ Because the symlink update is atomic, users rarely notice downtime.
Troubleshooting Common Issues
500 Internal Server Error
Most commonly caused by:
- Incorrect file permissions
- Missing PHP extensions
- Wrong PHP-FPM socket version
- Broken symlink paths
Check that storage/ and bootstrap/cache/ are writable.
Blank Page After Deployment
Often caused by:
- Incorrect Nginx root path
- Missing
.env
- Application key not generated
Make sure:
APP_ENV=production
APP_DEBUG=false
SSH Action Fails
Usually due to:
- Incorrect private key format
- Wrong SSH username
- Server firewall rules
Test SSH access manually before debugging CI.
Final Thoughts
This setup gives you a professional, automated pipeline. You push to main, and GitHub Actions handles the rest — running tests, building assets, and switching the live site without dropping connections.
Happy Deploying! 🚀
🔗 Stay Connected
Follow me for more Laravel tutorials, dev tips, deployment workflows and solving real-world production headaches.
- Follow me on LinkedIn
- Follow me here on Medium and join my mailing list
- Follow me here on Dev.to for more in-depth content and tutorials!
Found this article useful?
🙏 Show your support by clapping 👏, subscribing 🔔, sharing to social networks