DEV Community: Ali Sahin

Deploy Next.js Application on AWS Lightsail with GitHub Actions

Ali Sahin — Thu, 12 Feb 2026 06:10:19 +0000

In this article, we'll walk through deploying Next.js and Node.js applications on AWS Lightsail using Nginx, PM2, GitHub Actions, and Cloudflare.

Prerequisites

Before starting, ensure you have:

AWS account with Lightsail access
GitHub account for repository hosting
Cloudflare account for DNS management
Domain name pointed to Cloudflare nameservers
Basic knowledge of Linux commands and Git
Node.js applications ready for deployment

Architecture Overview

Our deployment architecture includes:

AWS Lightsail: Virtual private server hosting the applications
Nginx: Reverse proxy routing traffic to applications
PM2: Process manager keeping Node.js apps running
GitHub Actions: CI/CD pipeline for automated deployments
Cloudflare: DNS management and SSL/TLS termination

Performance Improvement

This architecture provides several performance benefits:

Application-Level Performance:
Nginx serves as an efficient reverse proxy, handling SSL termination and static file serving, which reduces load on the Node.js applications. PM2 enables zero-downtime deployments through its cluster mode and automatic restarts, ensuring applications remain available during updates.

Caching and CDN:
Cloudflare's global CDN caches static assets at edge locations worldwide, significantly reducing latency for users. Nginx can also implement additional caching layers for API responses and dynamic content, further improving response times.

Resource Optimization:
PM2's cluster mode allows Node.js applications to utilize all available CPU cores, maximizing server resource utilization. Lightsail provides predictable performance with fixed resource allocations, making capacity planning straightforward.

Implementation Steps

Step 1: Set Up AWS Lightsail Instance

Create a new Lightsail instance:

# Use AWS Console or CLI
aws lightsail create-instances \
  --instance-names my-app-server \
  --availability-zone us-east-1a \
  --blueprint-id ubuntu_22_04 \
  --bundle-id nano_2_0

Console Steps:

Log in to AWS Lightsail console
Click "Create instance"
Select Linux/Unix platform
Choose Ubuntu 22.04 LTS blueprint
Select an instance plan (recommend at least $5/month for production)
Name your instance (e.g., "my-app-server")
Click "Create instance"

Once the instance is running, note its static IP address. Configure the Lightsail firewall:

Firewall Rules:

SSH (Port 22) - Your IP only
HTTP (Port 80) - All traffic
HTTPS (Port 443) - All traffic

Step 2: Connect and Set Up the Server

Connect to your Lightsail instance via SSH:

# Download the SSH key from Lightsail console
chmod 400 lightsail-key.pem
ssh -i lightsail-key.pem ubuntu@YOUR_STATIC_IP

Update the system and install required packages:

# Update package list
sudo apt update && sudo apt upgrade -y

# Install Nginx and Git
sudo apt install -y nginx git

# Install Node.js 24.x (LTS)
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs

# Verify installation
node --version
npm --version

# Install PM2 globally
sudo npm install -g pm2

# Verify PM2 installation
pm2 --version

Step 3: Configure Nginx as Reverse Proxy

Create Nginx configuration for your applications:

# Create configuration file
sudo nano /etc/nginx/sites-available/myapp

Add the following configuration:


server
{
    listen 80;
    server_name yourdomain.com;

    location /api
    {
        proxy_pass http://localhost:4000; # backend port
        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;

    # CORS headers (if needed)
    add_header Access-Control-Allow-Origin *;

    # Rate limiting for API endpoints
    location /api {
        limit_req zone=api_limit burst=20 nodelay;
        proxy_pass http://localhost:4000;
        proxy_set_header Host $host;
    }

    }

    location /
    {
        proxy_pass http://localhost:3000; # frontend port
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;

    # Cache static assets
    location /_next/static {
      proxy_pass http://localhost:3000;
      proxy_cache_valid 60m;
      add_header Cache-Control "public, max-age=3600, immutable";
    }
    }
}

# Rate limiting configuration
limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;

Enable the configuration:

# Create symbolic link
sudo ln -s /etc/nginx/sites-available/myapp /etc/nginx/sites-enabled/

# Remove default configuration
sudo rm /etc/nginx/sites-enabled/default

# Test configuration
sudo nginx -t

# Reload Nginx
sudo systemctl reload nginx

# Enable Nginx to start on boot
sudo systemctl enable nginx

Step 4: Set Up Application Directories

Create directories for your applications:

# Create application directories
sudo mkdir -p /var/www/my-app

# Set ownership to ubuntu user
sudo chown -R ubuntu:ubuntu /var/www/my-app

# Create environment files directory
mkdir -p /home/ubuntu/.env-files

Step 5: Configure PM2 for Process Management

Create PM2 ecosystem configuration file:

# Create ecosystem file
nano /var/www/ecosystem.config.js

Add the following PM2 configuration:

module.exports = {
  apps: [
    {
      name: "frontend",
      cwd: "/var/www/my-app/frontend",
      script: "npm",
      args: "start",
      env: {
        NODE_ENV: "production",
        PORT: 3000,
      },
      instances: 2,
      exec_mode: "cluster",
      autorestart: true,
      watch: false,
      max_memory_restart: "500M",
      error_file: "/var/www/logs/nextjs-error.log",
      out_file: "/var/www/logs/nextjs-out.log",
      merge_logs: true,
      time: true,
    },
    {
      name: "api",
      cwd: "/var/www/my-app/api",
      script: "dist/index.js", // or 'src/index.js' if not using TypeScript
      env: {
        NODE_ENV: "production",
        PORT: 4000,
      },
      instances: 2,
      exec_mode: "cluster",
      autorestart: true,
      watch: false,
      max_memory_restart: "500M",
      error_file: "/var/www/logs/api-error.log",
      out_file: "/var/www/logs/api-out.log",
      merge_logs: true,
      time: true,
    },
  ],
};

Create logs directory:

sudo mkdir -p /var/www/logs
sudo chown -R ubuntu:ubuntu /var/www/logs

Step 6: Configure Cloudflare DNS and SSL

DNS Configuration:

Log in to your Cloudflare dashboard
Select your domain
Go to DNS settings
Add A records:
- Name: nextapp, Content: YOUR_LIGHTSAIL_STATIC_IP, Proxy: Enabled (Orange cloud)
- Name: api, Content: YOUR_LIGHTSAIL_STATIC_IP, Proxy: Enabled (Orange cloud)

SSL/TLS Configuration:

Go to SSL/TLS settings in Cloudflare
Set SSL/TLS encryption mode to "Flexible" (or "Full" if you configure SSL on Lightsail)
Enable "Always Use HTTPS"
Enable "Automatic HTTPS Rewrites"
For production, consider "Full (Strict)" mode with origin certificates

Optional: Generate Cloudflare Origin Certificate (for Full Strict mode):

In Cloudflare, go to SSL/TLS → Origin Server
Click "Create Certificate"
Keep default settings (RSA, 15-year validity)
Save the certificate and private key

Install on Lightsail:

# Save certificate
sudo nano /etc/ssl/certs/cloudflare-origin.pem
# Paste certificate content

# Save private key
sudo nano /etc/ssl/private/cloudflare-origin.key
# Paste private key content

# Set permissions
sudo chmod 644 /etc/ssl/certs/cloudflare-origin.pem
sudo chmod 600 /etc/ssl/private/cloudflare-origin.key

Update Nginx configuration to use SSL:

server {
    listen 443 ssl http2;
    server_name yourdomain.com;

    ssl_certificate /etc/ssl/certs/cloudflare-origin.pem;
    ssl_certificate_key /etc/ssl/private/cloudflare-origin.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

# Redirect HTTP to HTTPS
server {
    listen 80;
    server_name yourdomain.com;
    return 301 https://$server_name$request_uri;
}

Step 7: Set Up GitHub Actions SSH Access

Generate SSH key for GitHub Actions:

# On your Lightsail instance, create deployment user SSH key
ssh-keygen -t ed25519 -C "myapp-github-actions" -f ~/.ssh/myapp-github-actions -N ""

# Add public key to authorized_keys
cat ~/.ssh/myapp-github-actions.pub >> ~/.ssh/authorized_keys

# Display private key (copy this for GitHub Secrets)
cat ~/.ssh/myapp-github-actions

Add Secrets to GitHub Repository:

Go to your GitHub repository
Navigate to Settings → Secrets and variables → Actions
Add the following secrets:
- LIGHTSAIL_HOST: Your Lightsail static IP
- LIGHTSAIL_USERNAME: ubuntu
- LIGHTSAIL_SSH_KEY: Contents of the private key from above
- LIGHTSAIL_PORT: 22

Step 8: Create GitHub Actions Workflow for monorepo Application

Create .github/workflows/deploy-to-lightsail.yml:

name: Deploy To Lightsail

on:
  push:
    branches:
      - main

jobs:
  build-deploy:
    name: Build & Deploy
    runs-on: ubuntu-latest
    continue-on-error: false
    outputs:
      node_modules_cache_key: ${{ steps.cache.outputs.cache-hit }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v5

      - name: Use Node.js 24
        uses: actions/setup-node@v4
        with:
          node-version: 24

      - name: Cache node_modules
        id: cache
        uses: actions/cache@v4
        with:
          path: |
            node_modules
            ~/.npm
          key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}

      # ---------------- Backend Build ----------------
      - name: Install backend dependencies
        working-directory: api
        run: npm ci

      - name: Build backend
        working-directory: api
        run: npm run build

      # ---------------- Frontend Build ----------------
      - name: Install frontend dependencies
        working-directory: frontend
        run: npm ci

      - name: Build frontend
        working-directory: frontend
        run: npm run build

      # ---------------- Package Artifacts ----------------
      - name: Prepare deployment package
        run: |
          mkdir -p deploy/api deploy/frontend
          cp -r api/dist deploy/api/
          cp api/package*.json deploy/api/
          cp -r frontend/.next frontend/public frontend/package*.json deploy/frontend/
          cp ecosystem.config.js deploy/

      # ---------------- Deploy to Server ----------------
      - name: Deploy via rsync
        uses: burnett01/rsync-deployments@7.0.1
        with:
          switches: -avzr --delete
          path: deploy/
          remote_path: /var/www/my-app
          remote_host: ${{ secrets.SERVER_IP }}
          remote_user: ${{ secrets.SERVER_USER }}
          remote_key: ${{ secrets.SSH_PRIVATE_KEY }}

      # ---------------- Install & Restart on Server ----------------
      - name: SSH and restart apps
        uses: appleboy/ssh-action@v1.2.2
        with:
          host: ${{ secrets.SERVER_IP }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          script: |
            cp ~/.env-files/.env.api /var/www/my-app/api/.env            
            cp ~/.env-files/.env.frontend /var/www/my-app/frontend/.env.production
            cd /var/www/my-app/api
            npm ci
            cd /var/www/my-app/frontend
            npm ci --omit=dev
            cd /var/www/my-app
            pm2 startOrRestart ecosystem.config.js

Step 9: Test GitHub Actions Deployment

Push changes to your main branch to trigger the workflow:

git add .
git commit -m "Set up GitHub Actions deployment"
git push origin main

Monitor the Actions tab in your GitHub repository to ensure the deployment completes successfully.

Step 10: Initial Manual Deployment

Before using GitHub Actions, manually deploy your applications:

# Clone your repository
cd /var/www/my-app
git clone https://github.com/yourusername/my-app.git .

# Build Next.js app
cd /var/www/my-app/frontend
npm install
npm run build

# Build Node.js API
cd /var/www/my-app/api
npm install
npm run build  # If using TypeScript

# Start applications with PM2
pm2 start /var/www/my-app/ecosystem.config.js

# Save PM2 configuration
pm2 save

# Set PM2 to start on system boot
pm2 startup
# Follow the instructions provided by the command

Step 11: Configure Environment Variables

Store environment variables securely:

# Create .env file for Next.js app
nano /var/www/my-app/frontend/.env.production

# Add your variables
NEXT_PUBLIC_API_URL=https://yourdomain.com/api
DATABASE_URL=your_database_url
API_SECRET_KEY=your_secret_key

# Create .env file for Node.js API
nano /var/www/my-app/api/.env

# Add your variables
PORT=4000
DATABASE_URL=your_database_url
JWT_SECRET=your_jwt_secret
NODE_ENV=production

# Secure the files
chmod 600 /var/www/my-app/frontend/.env.production
chmod 600 /var/www/my-app/api/.env

Add environment variables to GitHub Secrets for use in workflows if needed.

Verification

After deployment, verify everything is working:

# Check PM2 status
pm2 status

# View application logs
pm2 logs nextjs-app --lines 50
pm2 logs nodejs-api --lines 50

# Check Nginx status
sudo systemctl status nginx

# Test local endpoints
curl http://localhost:3000
curl http://localhost:4000

# Test public endpoints
curl https://yourdomain.com
curl https://yourdomain.com/api

Security Enhancement

SSL/TLS Encryption:
Cloudflare provides free SSL certificates with automatic renewal, ensuring all traffic between users and your applications is encrypted. Cloudflare's Full (Strict) SSL mode encrypts traffic end-to-end, from users to Cloudflare to your Lightsail instance.

DDoS Protection:
Cloudflare's built-in DDoS protection shields your applications from attacks at the edge, preventing malicious traffic from reaching your Lightsail instance. This protection is included in the free tier and automatically scales with attack volume.

Firewall and Access Control:
Lightsail's firewall allows you to restrict access to specific ports, ensuring only necessary services are exposed. Cloudflare's WAF (Web Application Firewall) can be configured to block common attack patterns and malicious requests before they reach your server.

Secure Deployments:
GitHub Actions with OIDC or SSH key authentication eliminates the need for long-lived credentials in your CI/CD pipeline. PM2 runs applications with limited user privileges, following the principle of least privilege.

Cost Efficiency

Predictable Pricing:
AWS Lightsail offers fixed monthly pricing starting at $3.50/month, including data transfer allowances. This predictable cost structure makes budgeting simple compared to pay-per-use EC2 instances.

Cloudflare Free Tier:
Cloudflare's free tier includes DNS management, SSL certificates, and DDoS protection at no cost. The CDN caching reduces bandwidth usage on your Lightsail instance, potentially allowing you to use a smaller instance size.

Resource Consolidation:
Hosting multiple applications on a single Lightsail instance with Nginx as a reverse proxy maximizes resource utilization. PM2's efficient process management ensures applications use only necessary resources, preventing waste.

No Additional Service Costs:
Unlike managed container services or serverless platforms, Lightsail with Nginx and PM2 has no additional service fees—you only pay for the compute instance.

Troubleshooting

Issue: PM2 Applications Not Starting

Symptoms: PM2 shows applications as "errored" or "stopped"

Solution:

# Check detailed logs
pm2 logs nextjs-app --lines 100

# Check if port is already in use
sudo netstat -tulpn | grep :3000

# Verify Node.js version
node --version

# Restart with verbose output
pm2 delete nextjs-app
pm2 start /var/www/ecosystem.config.js --only nextjs-app

Issue: Nginx 502 Bad Gateway

Symptoms: Nginx returns 502 error when accessing applications

Solution:

# Check if applications are running
pm2 status

# Verify applications are listening on correct ports
curl http://localhost:3000
curl http://localhost:4000

# Check Nginx error logs
sudo tail -f /var/log/nginx/error.log

# Test Nginx configuration
sudo nginx -t

# Restart Nginx
sudo systemctl restart nginx

Issue: GitHub Actions Deployment Fails

Symptoms: GitHub Actions workflow shows SSH connection errors

Solution:

Verify SSH key is correctly added to GitHub Secrets
Check Lightsail firewall allows SSH from GitHub Actions IPs
Test SSH connection manually:

ssh -i myapp-github-actions ubuntu@YOUR_LIGHTSAIL_IP

Ensure authorized_keys file has correct permissions:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

Issue: Cloudflare SSL Errors

Symptoms: "Too many redirects" or "SSL handshake failed"

Solution:

Check Cloudflare SSL mode matches your Nginx configuration:
- Flexible: No SSL on Lightsail (HTTP only)
- Full: Self-signed certificate on Lightsail
- Full (Strict): Cloudflare Origin Certificate on Lightsail
Disable "Always Use HTTPS" temporarily in Cloudflare
Check Nginx SSL certificate paths are correct
Verify Nginx is listening on port 443:

sudo netstat -tulpn | grep :443

Issue: High Memory Usage

Symptoms: PM2 apps restarting frequently due to memory limits

Solution:

# Check memory usage
pm2 status
free -h

# Adjust max_memory_restart in ecosystem.config.js
# Reduce number of instances if needed
# Consider upgrading Lightsail plan

# Monitor memory over time
pm2 monit

Monitoring and Maintenance

PM2 Monitoring:

# View real-time monitoring
pm2 monit

# View process list
pm2 status

# View logs
pm2 logs

# Flush logs
pm2 flush

Nginx Monitoring:

# Check access logs
sudo tail -f /var/log/nginx/access.log

# Check error logs
sudo tail -f /var/log/nginx/error.log

# Check Nginx status
sudo systemctl status nginx

System Monitoring:

# Check disk space
df -h

# Check memory usage
free -h

# Check CPU usage
top

# Check running processes
ps aux

Regular Maintenance Tasks:

Update system packages monthly:

sudo apt update && sudo apt upgrade -y

Rotate logs to prevent disk space issues:

pm2 install pm2-logrotate
pm2 set pm2-logrotate:max_size 10M
pm2 set pm2-logrotate:retain 7

Monitor Lightsail metrics in AWS console
Review Cloudflare analytics for traffic patterns
Set up CloudWatch alarms for Lightsail instance health

Next Steps

After successfully deploying your applications, consider these enhancements:

Caching Layer:

Install Redis for session storage and caching
Configure Nginx caching for static assets
Use Cloudflare's cache rules for optimal CDN performance

Monitoring and Logging:

Set up PM2 Plus for advanced monitoring
Configure CloudWatch Logs for centralized logging
Set up Uptime monitoring with services like UptimeRobot

Backup Strategy:

Configure Lightsail automatic snapshots
Set up database backup scripts
Store critical data in S3

Scaling Considerations:

Use Lightsail load balancer with multiple instances for high availability
Migrate to ECS or EC2 Auto Scaling Groups for advanced scaling needs
Consider using Amazon CloudFront in addition to Cloudflare for AWS-native CDN

Security Hardening:

Configure Cloudflare WAF rules for application protection
Implement rate limiting at multiple layers
Regular security updates and vulnerability scanning

Summary

In this tutorial, we successfully deployed Next.js and Node.js applications on AWS Lightsail using a production-ready stack. By combining Nginx as a reverse proxy, PM2 for robust process management, GitHub Actions for automated CI/CD, and Cloudflare for DNS and SSL management, we created a reliable, secure, and cost-effective deployment pipeline.

Optimized GitHub Actions Pipeline for Laravel Application

Ali Sahin — Tue, 12 Aug 2025 13:24:01 +0000

In this article, we'll walk through implementing a CI pipeline for a Laravel application that automates code quality checks, security scanning, and parallel testing. This pipeline will help you catch issues early and maintain code standards.

What You’ll Need

Before implementing the CI pipeline, ensure you have:

Your Laravel app code hosted on GitHub
Test suite set up with PHPUnit

Pipeline Overview

Our CI pipeline consists of four main components:

Code Quality Checks - Ensuring consistent code style and identifying potential issues
Security Scanning - Detecting vulnerabilities in dependencies
Parallel Testing - Running tests efficiently across multiple jobs
Notifications - Keeping team members informed of pipeline status

Let's dive into each component and see how to implement them effectively.

Step 1: Code Quality Checks

Maintaining consistent code style and identifying potential issues early is crucial for code maintainability. Our pipeline implements two key quality checks:

Laravel Pint for Code Styling

Laravel Pint is an opinionated PHP code style fixer for minimalists. It automatically formats your code according to Laravel's coding standards.

PHPStan for Static Analysis

PHPStan focuses on finding errors in your code without actually running it. It catches whole classes of bugs even before you write tests for the code.

Implementation in workflow:

- name: Run Laravel Pint (Code Style)
  run: vendor/bin/pint --test

- name: Run PHPStan (Static Analysis)
  run: vendor/bin/phpstan analyse --memory-limit=1G

Step 2: Security Scanning

Our pipeline includes security scanning using Composer's built-in audit tool which checks your dependencies against a database of known security vulnerabilities. It can be configured to fail the pipeline based on severity levels.

Implementation in workflow:

- name: Run Composer Audit
  run: composer audit --ignore-severity medium --locked

This command checks for vulnerabilities and ignores medium severity issues, but will fail the pipeline for high or critical vulnerabilities.

Step 3: Parallel Testing Implementation

Testing is a critical part of any application, but as your test suite grows, it can become time-consuming. Our pipeline implements parallel testing to significantly reduce execution time.

Test Splitting Strategy

The pipeline splits tests into 10 parallel jobs, each running a portion of the test suite:

strategy:
    matrix:
        split: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] # 10 parallel jobs

Test Distribution

Tests are distributed evenly across jobs using the split command:

# Find all test files and split them into 10 chunks
mkdir -p .test-splits
find tests/Unit -name "*Test.php" | sort | split -n l/10 -d - .test-splits/test_
echo "TEST_FILES=$(cat .test-splits/test_$(printf '%02d' $(( ${{ matrix.split }} - 1 ))))" >> $GITHUB_ENV

ParaTest for Parallel Execution

ParaTest is used to run PHPUnit tests in parallel within each job:

- name: Run ParaTest (Job ${{ matrix.split }})
  run: |
      echo "Running tests for chunk ${{ matrix.split }}"
      vendor/bin/paratest \
        --runner=WrapperRunner \
        --processes=4 \
        --functional \
        --colors \
        --filter=$(echo $TEST_FILES | tr '\n' ',' | sed 's/,$//')

This approach can reduce test execution time by up to 90% compared to running tests sequentially.

Step 4: Send Notifications

Keeping your team informed about pipeline status helps maintain awareness of the application's health. The pipeline includes optional Slack notifications.

Implementation in workflow:

notifications:
    runs-on: ubuntu-latest
    needs: [tests]
    steps:
        - name: Notify Slack
          uses: 8398a7/action-slack@v4
          with:
              status: ${{ job.status }}
              fields: repo,commit,author
          env:
              SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
              SLACK_WEBHOOK_TYPE: INCOMING_WEBHOOK

Best Practices and Optimization Tips

Separated jobs: Separating jobs improves both performance and maintainability of the pipeline. By running these jobs in parallel, overall execution time is reduced, which becomes increasingly valuable as the codebase grows. This separation also makes it easier to pinpoint the source of failures, whether they are related to code quality, security vulnerabilities, or functional issues. Resource usage is optimized since each job can be configured according to its specific demands, and failures can be retried independently without re-running the entire pipeline. Additionally, each job can operate in a tailored environment with only the necessary dependencies, minimizing overhead and reducing potential conflicts.

Cache Dependencies: Use GitHub Actions caching to speed up dependency installation:

- name: Cache dependencies
  uses: actions/cache@v4
  with:
      path: |
          ~/.composer/cache
          vendor
      key: dependencies-${{ hashFiles('**/composer.lock') }}

Matrix Testing for PHP Versions: Test your application against multiple PHP versions:
```
strategy:
    matrix:
        php: [8.1, 8.2, 8.3]
```

Here's a full example for the CI pipeline

name: CI Pipeline

on:
  push:
    branches: ["main"]
  pull_request:
    branches: ["*"]

jobs:
  # -----------------------
  # 1. Code Quality Checks
  # -----------------------
  quality:
    name: Code Quality Checks
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: 8.2
          extensions: mbstring, pdo, bcmath
          tools: composer:v2

      - name: Cache dependencies
        uses: actions/cache@v4
        with:
          path: |
            ~/.composer/cache
            vendor
          key: dependencies-${{ hashFiles('**/composer.lock') }}
          restore-keys: |
            dependencies-

      - name: Install dependencies
        run: composer install --no-progress --prefer-dist --optimize-autoloader

      - name: Run Laravel Pint (Code Style)
        run: vendor/bin/pint --test

      - name: Run PHPStan (Static Analysis)
        run: vendor/bin/phpstan analyse --memory-limit=1G

  # -----------------------
  # 2.   Security Checks
  # -----------------------
  security:
    name: Security Checks
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: 8.2
          extensions: mbstring, pdo, bcmath
          tools: composer:v2

      - name: Cache dependencies
        uses: actions/cache@v4
        with:
          path: |
            ~/.composer/cache
            vendor
          key: dependencies-${{ hashFiles('**/composer.lock') }}
          restore-keys: |
            dependencies-

      - name: Install dependencies
        run: composer install --no-progress --prefer-dist --optimize-autoloader

      - name: Run Composer Audit
        run: composer audit --ignore-severity medium --locked

  # -----------------------
  # 3. Run Tests (Matrix)
  # -----------------------
  tests:
    name: PHPUnit (Parallel Job ${{ matrix.split }})
    runs-on: ubuntu-latest
    needs: [quality, security]
    strategy:
      matrix:
        split: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] # 10 parallel jobs
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: 8.2
          extensions: mbstring, pdo, bcmath, sqlite
          tools: composer:v2

      - name: Cache dependencies
        uses: actions/cache@v4
        with:
          path: |
            ~/.composer/cache
            vendor
          key: dependencies-${{ hashFiles('**/composer.lock') }}
          restore-keys: |
            dependencies-

      - name: Install dependencies
        run: composer install --no-progress --prefer-dist --optimize-autoloader

      - name: Install ParaTest
        run: composer require --dev brianium/paratest

      - name: Prepare Laravel
        run: |
          cp .env.example .env
          php artisan key:generate
          php artisan config:cache

      - name: Split Tests
        id: split-tests
        run: |
          # Find all test files and split them into 10 chunks
          mkdir -p .test-splits
          find tests/Unit -name "*Test.php" | sort | split -n l/10 -d - .test-splits/test_
          echo "TEST_FILES=$(cat .test-splits/test_$(printf '%02d' $(( ${{ matrix.split }} - 1 ))))" >> $GITHUB_ENV

      - name: Run ParaTest (Job ${{ matrix.split }})
        run: |
          echo "Running tests for chunk ${{ matrix.split }}"
          vendor/bin/paratest \
            --runner=WrapperRunner \
            --processes=4 \
            --functional \
            --colors \
            --filter=$(echo $TEST_FILES | tr '\n' ',' | sed 's/,$//')

You now have a professional CI pipeline that's designed for both performance and reliability. It optimizes execution time by running jobs sequentially, leveraging a matrix strategy, and caching dependencies to reduce execution time of the workflow. The workflow is structured with clear separation between jobs and steps, making troubleshooting more efficient. Security scanning is integrated into the process to align with DevSecOps best practices, and real-time notifications are sent to Slack to keep your team informed about deployment activities.

In the upcoming article, we’ll take the workflow a step further by introducing a continuous deployment (CD) stage.

Deploy Laravel App to a Linux Server Using GitHub Actions

Ali Sahin — Mon, 14 Jul 2025 10:15:14 +0000

In this guide, you’ll learn how to build a simple, secure, and automated deployment pipeline for your Laravel application using GitHub Actions and SSH. This setup will automatically deploy your app to a Linux server every time you push updates to a specific Git branch.

Whether you’re just getting started with CI/CD or want to streamline your team’s workflow, this step-by-step guide is designed to walk you through the process clearly and confidently.

What You’ll Need

Before we begin, make sure you have:

A Linux server you can SSH into.
Your Laravel app code hosted on GitHub.
Some Docker experience (since our deploy script uses Docker).

Step 1: Create an SSH Key to Let GitHub Talk to Your Server

Before we jump into creating SSH keys, let’s quickly understand what they are.

What Are Public and Private Keys?

SSH uses a key pair for secure communication:

The public key is like a lock. You place it on the server you want to access.
The private key is like the key that opens that lock. You keep this on your local machine (or in GitHub Secret vault).

Only someone with the private key can connect to the server where the public key is installed. This allows passwordless and secure logins, which is perfect for automation.

The public key (.pub file) goes on your server in ~/.ssh/authorized_keys.
The private key is added to your GitHub repository's secrets as SSH_KEY.

Now, let’s create that key pair.

Imagine your server is your home. You want GitHub to have a spare key so it can enter without ringing the bell (or typing a password).

Here’s how to give GitHub that key:

Open your terminal and run:

   ssh-keygen -t ed25519 -C "deploy-laravel-app-with-github-actions"

Hit Enter to accept the default location.
When it asks for a passphrase, just press Enter again (we want this to be automatic).

Find your keys:
- Private key: ~/.ssh/id_ed25519
- Public key: ~/.ssh/id_ed25519.pub
Add the public key to your server so it trusts GitHub:

   ssh-copy-id -i ~/.ssh/id_ed25519.pub user@your.server.ip

Replace user and your.server.ip with your server’s SSH username and IP address.

Copy the private key content so we can use it in GitHub Actions:

   cat ~/.ssh/id_ed25519

Step 2: Add Secrets in GitHub

GitHub needs to know how to log in to your server. So let’s give it all the details safely using Secrets.

In your GitHub repo, go to Settings > Secrets > Actions, then add:

Name	What to Put There
`HOST`	Your server's IP address or domain name
`USERNAME`	The SSH username (like `ubuntu`)
`SSH_KEY`	Paste your private key here (from last step)
`SSH_PORT`	Usually `22` unless you changed it
`APP_PATH`	The full path to your app on the server

Step 3: Write a Simple Deploy Script

This is a short script that tells your server what to do when it's time to deploy. Save it as .scripts/deploy.sh in your project:

#!/bin/bash
set -e

echo "🚀 Starting deployment..."

cd ..

# Put app in maintenance mode
(docker-compose exec app php artisan down) || true

# Install PHP dependencies
docker-compose exec app composer install --no-dev --no-interaction --prefer-dist --optimize-autoloader

# Clear and rebuild cache
docker-compose exec app php artisan clear-compiled
docker-compose exec app php artisan optimize:clear

# Run migrations
docker-compose exec app php artisan migrate --force

# Bring app back online
docker-compose exec app php artisan up

echo "✅ Deployment finished!"

Note: Change app to whatever your Laravel container is named if it’s different.

Step 4: Let GitHub Deploy Automatically

Now for the magic. Create a file in your project at:

.github/workflows/deploy.yml

Paste this in:

name: Deploy to Server

on:
  push:
    branches:
      - develop

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: SSH into server and deploy
        uses: appleboy/ssh-action@v1.2.0
        with:
          host: ${{ secrets.HOST }}
          username: ${{ secrets.USERNAME }}
          key: ${{ secrets.SSH_KEY }}
          port: ${{ secrets.SSH_PORT }}
          script: |
            set -e
            cd ${{ secrets.APP_PATH }}
            git config --local url."https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/".insteadOf "https://github.com/"
            git fetch origin
            git reset --hard origin/develop
            git config --local --remove-section url."https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/"
            bash .scripts/deploy.sh

Here’s what’s happening:

GitHub waits for a push to the develop branch.
It connects to your server.
It pulls the latest code.
It runs your deploy.sh script.

Breaking Down the `script` Section

Let’s go over what’s happening in the script part of the SSH step:

script: |
  set -e
  cd ${{ secrets.APP_PATH }}
  git config --local url."https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/".insteadOf "https://github.com/"
  git fetch origin
  git reset --hard origin/develop
  git config --local --remove-section url."https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/"
  bash .scripts/deploy.sh

set -e: Stops the script immediately if any command fails.
cd ${{ secrets.APP_PATH }}: Navigates to your Laravel app folder on the server.
The git config commands:
- Temporarily override GitHub URLs to use the built-in GITHUB_TOKEN so your server can fetch private repos.
- This is useful when your Laravel project is private or depends on private packages.
git fetch origin: Pulls the latest code from the remote repository.
git reset --hard origin/develop: Replaces local code with the latest from the develop branch. (helpful if you made some changes on the server, like a quick fix or debugging, so you can reset it to the latest code)
git config --local --remove-section: Cleans up the temporary GitHub auth config. (as the GITHUB_TOKEN is only useed for this deployment, and will expires after the action runs)
bash .scripts/deploy.sh: Finally runs your deployment script.

Note: You don’t need to manually add GITHUB_TOKEN in your GitHub Secrets — it’s automatically provided by GitHub Actions at runtime.

Step 5: Test It!

Now try it out:

Push any change to your develop branch.
Go to your GitHub repo → Actions tab.
Watch the magic happen! If it works, your Laravel app gets updated on the server instantly.

You now have a secure, automated CI/CD pipeline using GitHub Actions to deploy your Laravel app to a remote Linux server using SSH.

In the next article, we'll take things a step further by adding features like code quality checks, automated testing, and send notifications to enhance your CI/CD pipeline. Stay tuned!

DEV Community: Ali Sahin

Deploy Next.js Application on AWS Lightsail with GitHub Actions

Prerequisites

Architecture Overview

Performance Improvement

Implementation Steps

Step 1: Set Up AWS Lightsail Instance

Step 2: Connect and Set Up the Server

Step 3: Configure Nginx as Reverse Proxy

Step 4: Set Up Application Directories

Step 5: Configure PM2 for Process Management

Step 6: Configure Cloudflare DNS and SSL

Step 7: Set Up GitHub Actions SSH Access

Step 8: Create GitHub Actions Workflow for monorepo Application

Step 9: Test GitHub Actions Deployment

Step 10: Initial Manual Deployment

Step 11: Configure Environment Variables

Verification

Security Enhancement

Cost Efficiency

Troubleshooting

Issue: PM2 Applications Not Starting

Issue: Nginx 502 Bad Gateway

Issue: GitHub Actions Deployment Fails

Issue: Cloudflare SSL Errors

Issue: High Memory Usage

Monitoring and Maintenance

Next Steps

Summary

Optimized GitHub Actions Pipeline for Laravel Application

What You’ll Need

Pipeline Overview

Step 1: Code Quality Checks

Laravel Pint for Code Styling

PHPStan for Static Analysis

Step 2: Security Scanning

Step 3: Parallel Testing Implementation

Test Splitting Strategy

Test Distribution

ParaTest for Parallel Execution

Step 4: Send Notifications

Best Practices and Optimization Tips

Deploy Laravel App to a Linux Server Using GitHub Actions

What You’ll Need

Step 1: Create an SSH Key to Let GitHub Talk to Your Server

What Are Public and Private Keys?

Step 2: Add Secrets in GitHub

Step 3: Write a Simple Deploy Script

Step 4: Let GitHub Deploy Automatically

Breaking Down the script Section

Step 5: Test It!

Breaking Down the `script` Section