Automating Laravel Deployment with GitHub Actions

This guide provides a step-by-step process for automating Laravel 12 deployments using GitHub Actions to a Virtual Private Server (VPS). Although this tutorial uses AWS Lightsail as the deployment environment, the same process is applicable to any Linux-based VPS or dedicated server.

The goal is to establish a repeatable, automated deployment pipeline that is easy to maintain and aligns with modern DevOps practices.

Prerequisites

• A Laravel 12 project hosted on GitHub.
• A Linux-based VPS (e.g., AWS Lightsail, DigitalOcean, Linode, etc.).
• SSH key access to the VPS.
• A deploy user on the server.
• A GitHub Personal Access Token (PAT) for authenticated repository access.
• Composer, Node.js, and NPM installed on the VPS.

Note: This deployment process does not manage or update Laravel’s .env file. In this example, the .env file should be manually configured on the server to connect to the required services. Managing .env files through deployment automation is outside the scope of this document.

Step 1: Set Up the Deployment User on the VPS

Log in to the VPS as root and create a new user for deployment.

sudo adduser deploy
sudo usermod -aG www-data deploy

Configure the SSH directory and set proper permissions.

sudo mkdir -p /home/deploy/.ssh
sudo chown -R deploy:deploy /home/deploy/.ssh
sudo chmod 700 /home/deploy/.ssh

Step 2: Generate SSH Keys for Server Authentication

Switch to the deploy user.

sudo su - deploy

Generate an SSH key.

ssh-keygen -t ed25519 -C "deploy@github-actions"

Use the default file location: /home/deploy/.ssh/deploy_key. Leave the passphrase empty.

Add the public key to the authorized keys.

cat ~/.ssh/deploy_key.pub >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

The deploy user can now accept SSH connections using this key.

Step 3: Configure GitHub CLI Authentication

The repository is using an HTTPS remote. To authenticate non-interactively during deployment, configure GitHub CLI on the VPS.

1. Generate a GitHub Personal Access Token (PAT) with repo scope.
2. Add this token to your GitHub repository secrets under the name GITHUB_TOKEN_PAT.

During deployment, the GitHub CLI will authenticate using this token to perform git pull operations securely.

Step 4: Configure File Permissions

Ensure that the deploy user has proper ownership and access to the Laravel project directory.

sudo chown -R deploy:www-data /var/www/sites/your-site.com
sudo find /var/www/sites/your-site.com -type d -exec chmod 775 {} \;
sudo find /var/www/sites/your-site.com -type f -exec chmod 664 {} \;

Step 5: Configure GitHub Actions for Automated Deployment

Create the following file in your GitHub repository:

.github/workflows/deploy.yml

name: Deploy Laravel to VPS

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v3

    - name: Set up SSH
      run: |
        mkdir -p ~/.ssh
        echo "${{ secrets.LIGHTSAIL_SSH_KEY }}" > ~/.ssh/id_rsa
        chmod 600 ~/.ssh/id_rsa
        ssh-keyscan -H ${{ secrets.LIGHTSAIL_HOST }} >> ~/.ssh/known_hosts

    - name: Deploy to VPS
      run: |
        ssh -i ~/.ssh/id_rsa -o StrictHostKeyChecking=no ${{ secrets.LIGHTSAIL_USER }}@${{ secrets.LIGHTSAIL_HOST }} << 'EOF'
          cd /var/www/sites/your-site.com

          echo "${{ secrets.GITHUB_TOKEN_PAT }}" | gh auth login --with-token

          php artisan down
          git pull origin main
          composer install --no-interaction --prefer-dist --optimize-autoloader
          php artisan migrate --force
          php artisan config:clear
          php artisan cache:clear
          npm install
          npm run build
          php artisan up
        EOF

GitHub Secrets Required

Deployment Workflow Summary

When code is pushed to the main branch:

1. GitHub Actions establishes an SSH connection to the VPS.
2. GitHub CLI authenticates using the provided Personal Access Token.
3. The server pulls the latest code from GitHub using git pull.
4. Laravel dependencies are installed using Composer.
5. Database migrations are executed.
6. NPM assets are installed and built.
7. Laravel caches are cleared.
8. The application is brought back online.

Key Notes

• This deployment process is designed for Laravel 12 but is adaptable to other Laravel versions.
• The process assumes the server environment is pre-configured with PHP, Nginx, Composer, Node.js, and NPM. (Here’s that guide)
• The Laravel .env file is not modified or deployed by this workflow. The environment configuration should be managed manually or through a separate, secure process.
• This deployment pipeline is suitable for Lightsail, DigitalOcean, Linode, or any Linux-based VPS.