
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:
- GitHub detects the push event.
- Runs your defined steps: checkout, tests, build, and deploy.
- 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 keySSH_KNOWN_HOSTS
– output ofssh-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
- Go to **Actions** in your GitHub repo.
- 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
andbootstrap/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
orpint
. - 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.