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 contentsSSH_KNOWN_HOSTS-- output ofssh-keyscan your-serverSSH_USER-- e.g.deploySSH_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
.envhas correct production values. - Run
php artisan key:generateif needed. - Set writable permissions for
storageandbootstrap/cache.
Troubleshooting
- GitHub Logs: Pinpoint step failures in the Actions tab.
- Laravel Logs: Check
storage/logs/laravel.logon 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
stagingbranch that deploys to a test server. - Database Seeding: Include
php artisan db:seedfor 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.
Related Articles
Building CI/CD Pipelines with GitHub Actions
Design production-grade CI/CD pipelines using GitHub Actions with matrix builds, environment protection rules, and automated rollback strategies.
LaravelLaravel Octane Performance Optimization Guide
Boost Laravel throughput 10x with Octane using Swoole and RoadRunner, connection pooling, memory management, and production deployment strategies.
LaravelLaravel Microservices with API Gateway Pattern
Design and implement a microservices architecture with Laravel, using an API Gateway for routing, rate limiting, and service discovery patterns.