Automating Deployment for Laravel Using Deployer and GitHub Actions
Overview
In this note, we outline how to automate the deployment process for a Laravel project using Deployer and GitHub Actions. The setup covers deploying to both staging and production environments, with different workflows for each environment. We also integrate necessary post-deployment tasks such as running migrations and restarting queues using Supervisor.
Prerequisites
Before setting up this automation, ensure the following:
- Deployer is installed in your Laravel project (
composer require deployer/deployer --dev
). - The deploy.php configuration file is created in the root of your project.
- SSH keys are set up correctly between GitHub Actions and your server for secure deployment.
Deployment Setup
Step 1: Creating the deploy.php
File
The deploy.php
file is essential for configuring Deployer. It defines the repository, shared directories, writable directories, and host settings for both staging and production environments. Below is an example.
1 |
|
Step 2: GitHub Actions Workflow
Staging Workflow (staging-deploy.yml
)
The following is an example of a GitHub Actions workflow file for deploying to the staging environment.
1 | name: Deploy to Staging |
Production Workflow (production-deploy.yml
)
The production workflow is similar but triggers on pushes to the main branch.
Step 3: Testing and Troubleshooting
Common Errors
No host selected
: This error occurs when Deployer cannot find the host based on the command selector. Make sure you pass the correct host (eitherstaging
orproduction
) when deploying.1
./vendor/bin/dep deploy staging
Call to undefined method
: This error may appear if you’re using the wrong Deployer version or method. In our case, ensure you’re following the Deployer 7.x documentation.
Step 4: Post-Deployment Tasks
Running Migrations: We use the
artisan:migrate
command to ensure that migrations are run automatically after deployment.Restarting Queues: If changes to the queue system are deployed, it’s essential to restart the queue workers. We achieve this by running
artisan:queue:restart
after deployment.Restarting Supervisor: If you’re managing workers using Supervisor, the deployment process includes commands to restart Supervisor with
supervisorctl
.
Summary
By combining Deployer and GitHub Actions, we’ve automated the deployment process for a Laravel project across both staging and production environments. This approach ensures the project is deployed and migrations are run automatically, and queue workers are restarted when necessary. The process is both scalable and adaptable for future projects.
Sources
Deployer Documentation: Hosts in Deployer 7.x
https://deployer.org/docs/7.x/hostsDeployer GitHub Action
https://github.com/deployphp/actionDeployer Official Documentation: Version 7.x
https://deployer.org/docs/7.x/GitHub Actions Documentation: Workflow Syntax
https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions