From Code to Production. A Guide to Automating Laravel Deployments with GitHub Actions

From Code to Production. A Guide to Automating Laravel Deployments with GitHub Actions

/Posted by / 560
Laravel Worker Ubuntu setup

Deploying Laravel Applications from GitHub to Your Server

Automate your Laravel deployments with a CI/CD pipeline powered by GitHub Actions. No more manual uploads or SSH sessions—let your tests run, assets build, and code deploy on every push to main.

Quick Navigation

What is GitHub Actions? How the Pipeline Runs Prerequisites SSH Key Setup CI/CD Workflow Monitoring & Logs Initial Server Setup Troubleshooting Enhancements

What is GitHub Actions?

GitHub Actions lets you define automated workflows in your repo that respond to events like pushes or pull requests. Use it to:

  • Automate Tests: Run your Laravel test suite on every PR or push.
  • Standardize Deployments: Execute the same deploy steps each time.
  • Boost Velocity: Ship code faster without manual steps.

How the Pipeline Runs

The workflow file in .github/workflows/deploy.yml listens for pushes to main. On each push:

  1. GitHub detects the push event.
  2. Runs your defined steps: checkout, tests, build, and deploy.
  3. Logs appear under the **Actions** tab for live debugging.

Prerequisites

  • GitHub Repo with your Laravel code.
  • Remote Server (PHP, Composer installed) with SSH access.
  • .env configured on server in the project directory.
  • SSH Keys generated locally and public key on server.

Setting Up SSH Keys

Generate and register:

ssh-keygen -t ed25519 -C "you@example.com"

Add to server’s authorized_keys:

cat id_ed25519.pub | ssh deploy@your-server "cat >> ~/.ssh/authorized_keys"

In GitHub → **Settings → Secrets & variables → Actions**, create:

  • SSH_PRIVATE_KEY – your private key
  • SSH_KNOWN_HOSTS – output of ssh-keyscan your-server
  • SSH_USER – e.g. deploy
  • SSH_HOST – your domain or IP

Creating the CI/CD Workflow

Create .github/workflows/deploy.yml:

name: Deploy Laravel

on:
  push:
    branches: [ "main" ]

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

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.1'
          extensions: mbstring, mysql, intl, bcmath

      - name: Install dependencies
        run: composer install --no-dev --optimize-autoloader

      - name: Run tests
        run: php artisan test

      - name: Start SSH agent
        uses: webfactory/ssh-agent@v0.5.4
        with:
          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}

      - name: Add known hosts
        run: |
          mkdir -p ~/.ssh
          echo "${{ secrets.SSH_KNOWN_HOSTS }}" >> ~/.ssh/known_hosts

      - name: Deploy
        run: |
          rsync -avz --delete --exclude=".git" -e "ssh -o StrictHostKeyChecking=no" ./ \
            ${{ secrets.SSH_USER }}@${{ secrets.SSH_HOST }}:/var/www/your-project
          ssh -o StrictHostKeyChecking=no ${{ secrets.SSH_USER }}@${{ secrets.SSH_HOST }} << 'EOF'
            cd /var/www/your-project
            composer install --no-dev --optimize-autoloader
            php artisan migrate --force
            php artisan config:cache
            php artisan route:cache
            php artisan view:cache
          EOF

Monitoring & Logs

  1. Go to **Actions** in your GitHub repo.
  2. Select the latest workflow run.
  3. Expand steps to view logs and status.

Initial Server Setup

  • Ensure .env has correct production values.
  • Run php artisan key:generate if needed.
  • Set writable permissions for storage and bootstrap/cache.

Troubleshooting

  • GitHub Logs: Pinpoint step failures.
  • Laravel Logs: Check storage/logs/laravel.log on server.
  • Permissions: Verify directory permissions.
  • SSH: Validate secrets and connectivity.

Enhancements

  • Branch-specific deploys: main → production, develop → staging.
  • Static analysis: add phpstan or pint.
  • Asset builds: run npm run production before deploy.
  • Release rollbacks: maintain versioned release dirs on server.

With this setup, every push to main tests, builds, and deploys your Laravel app—freeing you to focus on code, not deployments.

Related posts