Skip to main content

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

8 min read
Automate my Laravel deploys

We set up GitHub Actions to test, build and deploy every push to main.

Learn how to build a fully automated CI/CD pipeline for Laravel using GitHub Actions, covering SSH key setup, workflow configuration, testing, and deployment to production servers.

Deploying Laravel Applications from GitHub to Your Server

We can automate Laravel deployments with a CI/CD pipeline powered by GitHub Actions. This eliminates manual uploads and SSH sessions -- tests run, assets build, and code deploys automatically on every push to main.

What is GitHub Actions?

GitHub Actions allows us to define automated workflows in a repository that respond to events like pushes or pull requests. We can use it to:

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

How the Pipeline Runs

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

  • GitHub detects the push event.
  • Runs the defined steps: checkout, tests, build, and deploy.
  • Logs output and status for each step are available in the Actions tab.

Prerequisites

  • A Laravel application hosted in a GitHub repository.
  • A remote server (Ubuntu recommended) with SSH access.
  • PHP, Composer, and a web server (Nginx or Apache) installed on the server.

Setting Up SSH Keys

We need a deploy key so GitHub Actions can connect to our server securely.

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

Add the public key to the server's authorized_keys:

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

In GitHub, navigate to Settings > Secrets & variables > Actions and create:

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

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

  • Go to Actions in the GitHub repository.
  • Select the latest workflow run.
  • 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 in the Actions tab.
  • Laravel Logs: Check storage/logs/laravel.log on the server.
  • Permissions: Verify directory permissions for the deploy user.

Enhancements

  • Slack Notifications: Add a Slack webhook step to receive deployment alerts.
  • Staging Branch: Create a separate workflow for a staging branch that deploys to a test server.
  • Database Seeding: Include php artisan db:seed for staging environments.
  • Zero-Downtime Deploys: Use tools like Envoyer or a symlink-based strategy.

By following this guide, we have a robust, automated deployment pipeline that ensures every push to main is tested, built, and deployed without manual effort.

Frequently asked questions

How do I deploy a Laravel app automatically with GitHub Actions?

Add a workflow at .github/workflows/deploy.yml that runs on every push to main. The job checks out the code, sets up PHP, runs composer install --no-dev --optimize-autoloader and php artisan test, then loads an SSH key and copies the project to the server with rsync. A final SSH step runs Composer, migrations and the artisan cache commands in the project directory.

Which GitHub secrets does a Laravel deploy workflow need?

The workflow needs four repository secrets, created under Settings > Secrets & variables > Actions. SSH_PRIVATE_KEY holds the private key contents, SSH_KNOWN_HOSTS holds the output of ssh-keyscan for the server, SSH_USER is the deploy user such as deploy, and SSH_HOST is the server's domain or IP address.

How do I create an SSH deploy key for GitHub Actions?

Generate a key pair with ssh-keygen -t ed25519 -C "you@example.com", then append the public key to the server's authorized_keys, for example with cat id_ed25519.pub | ssh deploy@your-server "cat >> ~/.ssh/authorized_keys". Paste the private key into the SSH_PRIVATE_KEY secret in GitHub so the workflow can open the SSH connection to the server.

What commands should run on the server after a Laravel deploy?

Once rsync has copied the code to /var/www/your-project, the workflow connects over SSH and runs composer install --no-dev --optimize-autoloader, php artisan migrate --force, php artisan config:cache, php artisan route:cache and php artisan view:cache. The rsync step itself uses --delete and excludes the .git folder.

How should a server be prepared before the first GitHub Actions deploy of Laravel?

The server needs SSH access, PHP, Composer and a web server such as Nginx or Apache, and Ubuntu is the recommended base. Before the first deploy, make sure .env holds the correct production values, run php artisan key:generate if needed, and make storage and bootstrap/cache writable.

Where do I find logs when a Laravel GitHub Actions deploy fails?

Open the Actions tab in the GitHub repository, select the latest workflow run and expand the steps to find the one that failed. On the server, check storage/logs/laravel.log. Also verify the directory permissions for the deploy user on the server.

How do I add a staging deploy to a Laravel GitHub Actions pipeline?

Create a separate workflow that listens to a staging branch and deploys to a test server. The staging workflow can also run php artisan db:seed to fill the database with seed data. A Slack webhook step can be added to either workflow for deployment alerts.

Can GitHub Actions deploy Laravel with zero downtime?

Zero-downtime deploys are an enhancement on top of the basic workflow, using a tool like Envoyer or a symlink-based strategy. The basic GitHub Actions job copies files straight into /var/www/your-project with rsync and then runs migrations and cache commands in place.

Read how we handle it in DevOps as a Service.