DEV Community

Cover image for How to Auto-Deploy a Laravel App to DigitalOcean Using GitHub Actions
Jenuel Oras Ganawed
Jenuel Oras Ganawed

Posted on • Originally published at blog.jenuel.dev

How to Auto-Deploy a Laravel App to DigitalOcean Using GitHub Actions

#ai #programming #productivity

How to Auto-Deploy a Laravel App to DigitalOcean Using GitHub Actions

Deploying a Laravel application manually can become repetitive, especially when you frequently push updates to production. Instead of logging in to your server through SSH every time, you can automate the deployment process using GitHub Actions.

In this guide, you will learn how to set up a simple CI/CD workflow that automatically deploys your Laravel app to a DigitalOcean Droplet every time you push changes to the main branch.

With this setup, your workflow will look like this:

Push to main → GitHub Actions runs → SSH into Droplet → Pull latest code → Install dependencies → Build assets → Run migrations → Optimize Laravel → Restart queue workers
Enter fullscreen mode Exit fullscreen mode

What You Will Need

Before starting, make sure you already have the following:

  • A Laravel application hosted on GitHub

  • A DigitalOcean Droplet running Ubuntu

  • Your Laravel app already set up and working on the Droplet

  • Nginx or Apache configured for your Laravel app

  • PHP, Composer, Node.js, and npm installed on the server

  • Database connection already configured in your .env file

  • SSH access to your Droplet

  • Basic knowledge of GitHub repository settings

For better security, it is recommended to use a dedicated deploy user instead of the root user. However, this guide will use root in the examples to keep the setup simple. If you are deploying a production application, consider creating a separate limited-access user for deployments.

Step 1: Create a Laravel Deploy Script

First, create a deploy command inside your package.json file. This allows GitHub Actions to run one command on your server instead of writing all deployment commands directly inside the workflow file.

Open your package.json and add the following script:

"scripts": {
  "deploy": "git pull && COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --optimize-autoloader && npm ci && npm run build && php artisan migrate --force && php artisan config:cache && php artisan route:cache && php artisan view:cache && php artisan optimize"
}
Enter fullscreen mode Exit fullscreen mode

If your project does not have a package-lock.json file, use npm install instead of npm ci:

"scripts": {
  "deploy": "git pull && COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --optimize-autoloader && npm install && npm run build && php artisan migrate --force && php artisan config:cache && php artisan route:cache && php artisan view:cache && php artisan optimize"
}
Enter fullscreen mode Exit fullscreen mode

What Each Command Does

Command Purpose
git pull Pulls the latest code from GitHub
COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --optimize-autoloader Installs production PHP dependencies and optimizes Composer autoloading
npm ci Installs JavaScript dependencies using the lock file for consistent builds
npm run build Builds frontend assets for production
php artisan migrate --force Runs database migrations in production mode
php artisan config:cache Caches Laravel configuration
php artisan route:cache Caches Laravel routes
php artisan view:cache Compiles and caches Blade views
php artisan optimize Runs Laravel optimization commands

Important: Running php artisan migrate --force on production can change your database structure. Always make sure your migrations are tested and that you have a database backup strategy before deploying.

Step 2: Create the GitHub Actions Workflow

Next, create a GitHub Actions workflow file inside your Laravel project.

Create this file:

.github/workflows/deploy.yml
Enter fullscreen mode Exit fullscreen mode

Then add the following workflow:

name: Deploy to Production

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Deploy via SSH
        uses: appleboy/ssh-action@v1.2.0
        with:
          host: ${{ secrets.DROPLET_HOST }}
          username: ${{ secrets.DROPLET_USER }}
          key: ${{ secrets.DROPLET_SSH_KEY }}
          script: |
            cd /var/www/your-app
            npm run deploy
            php artisan queue:restart
Enter fullscreen mode Exit fullscreen mode

Replace this path with the actual location of your Laravel app on the Droplet:

/var/www/your-app
Enter fullscreen mode Exit fullscreen mode

For example:

script: |
  cd /var/www/my-laravel-app
  npm run deploy
  php artisan queue:restart
Enter fullscreen mode Exit fullscreen mode

The php artisan queue:restart command tells Laravel queue workers to restart gracefully so they can use the newly deployed code. If you are using Supervisor to manage your queue workers, Supervisor will automatically start them again.

Step 3: Generate a Deploy SSH Key on Your Local Machine

GitHub Actions needs SSH access to your Droplet. Instead of using your personal SSH key, it is better to create a dedicated SSH key for deployment.

Run this command on your local machine:

ssh-keygen -t ed25519 -C "your-app-github-deploy" -f ~/.ssh/your-app-github -N ""
Enter fullscreen mode Exit fullscreen mode

This will create two files:
File Purpose
~/.ssh/your-app-github Private key. This will be added to GitHub Secrets.
~/.ssh/your-app-github.pub Public key. This will be added to your Droplet.

Do not share the private key publicly. It should only be stored in GitHub Secrets.

Step 4: Add the Public Key to Your Droplet

Now add the public key to your Droplet so GitHub Actions can connect through SSH.

Mac or Linux 

ssh-copy-id -i ~/.ssh/your-app-github.pub root@YOUR_DROPLET_IP
Enter fullscreen mode Exit fullscreen mode

Windows PowerShell 

type $env:USERPROFILE\.ssh\your-app-github.pub | ssh root@YOUR_DROPLET_IP "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 700 ~/.ssh && chmod 600 ~/.ssh/authorized_keys"
Enter fullscreen mode Exit fullscreen mode

Replace YOUR_DROPLET_IP with your actual DigitalOcean Droplet IP address.

You can test the SSH connection using:

ssh -i ~/.ssh/your-app-github root@YOUR_DROPLET_IP
Enter fullscreen mode Exit fullscreen mode

If the connection works, GitHub Actions should also be able to connect once the private key is added to your repository secrets.

Step 5: Create a GitHub Deploy Key on the Droplet

Your GitHub Actions workflow can now connect to the Droplet, but the Droplet also needs permission to pull code from your GitHub repository.

SSH into your Droplet:

ssh root@YOUR_DROPLET_IP
Enter fullscreen mode Exit fullscreen mode

Then generate a new SSH key on the Droplet:

ssh-keygen -t ed25519 -C "your-app-droplet-deploy" -f ~/.ssh/your-app-github -N ""
Enter fullscreen mode Exit fullscreen mode

Print the public key:

cat ~/.ssh/your-app-github.pub
Enter fullscreen mode Exit fullscreen mode

Copy the output, then go to your GitHub repository:

Settings → Deploy keys → Add deploy key
Enter fullscreen mode Exit fullscreen mode

Add the deploy key using these values:
Field Value
Title DigitalOcean Droplet
Key Paste the public key from the Droplet
Allow write access Leave unchecked

Read-only access is enough because the Droplet only needs to pull code from GitHub.

After adding the deploy key, configure SSH on the Droplet to use this key when connecting to GitHub:

cat >> ~/.ssh/config <<'EOF'
Host github.com
  IdentityFile ~/.ssh/your-app-github
  StrictHostKeyChecking no
EOF

chmod 600 ~/.ssh/config
Enter fullscreen mode Exit fullscreen mode

Test if the Droplet can connect to GitHub:

ssh -T git@github.com
Enter fullscreen mode Exit fullscreen mode

If the key is configured correctly, GitHub should recognize the connection.

Step 6: Add GitHub Repository Secrets

Now add the SSH connection details to GitHub Secrets.

Go to your GitHub repository:

Settings → Secrets and variables → Actions → New repository secret
Enter fullscreen mode Exit fullscreen mode

Add the following secrets:
Secret Name Value
DROPLET_HOST Your Droplet IP address
DROPLET_USER Your SSH user, for example root
DROPLET_SSH_KEY The full contents of your local private key

To get the private key contents from your local machine:

Mac or Linux 

cat ~/.ssh/your-app-github
Enter fullscreen mode Exit fullscreen mode

Windows PowerShell 

cat $env:USERPROFILE\.ssh\your-app-github
Enter fullscreen mode Exit fullscreen mode

Copy everything, including these lines:

-----BEGIN OPENSSH PRIVATE KEY-----
...
-----END OPENSSH PRIVATE KEY-----
Enter fullscreen mode Exit fullscreen mode

Paste the full private key into the DROPLET_SSH_KEY secret.

Step 7: Push and Test the Deployment

After setting up the deploy script and workflow file, commit and push your changes to the main branch:

git add .github/workflows/deploy.yml package.json
git commit -m "Add auto-deploy pipeline"
git push origin main
Enter fullscreen mode Exit fullscreen mode

Then go to your GitHub repository and open the Actions tab.

If everything is configured correctly, you should see the deployment workflow running. A green checkmark means the deployment completed successfully.

How the Deployment Process Works

Here is the full process:

You push changes to main
        ↓
GitHub Actions starts the deployment workflow
        ↓
GitHub Actions connects to your Droplet through SSH
        ↓
The workflow goes to your Laravel project directory
        ↓
The server runs npm run deploy
        ↓
Laravel pulls the latest code from GitHub
        ↓
Composer installs production dependencies
        ↓
Node builds frontend assets
        ↓
Laravel runs migrations and optimization commands
        ↓
Queue workers restart gracefully
        ↓
Deployment is complete
Enter fullscreen mode Exit fullscreen mode

This removes the need to manually SSH into your server every time you want to deploy updates.

Troubleshooting Common Issues

git@github.com: Permission denied (publickey)

This usually means your Droplet does not have permission to pull from your GitHub repository.

To fix this:

  • Make sure you generated an SSH key on the Droplet.

  • Make sure the Droplet public key was added to GitHub Deploy Keys.

  • Make sure the repository remote uses SSH instead of HTTPS.

Check your remote URL:

git remote -v
Enter fullscreen mode Exit fullscreen mode

It should look like this:

git@github.com:username/repository.git
Enter fullscreen mode Exit fullscreen mode

If it uses HTTPS, update it:

git remote set-url origin git@github.com:username/repository.git
Enter fullscreen mode Exit fullscreen mode

composer: Continue as root/super user [yes]?

If you are deploying as root, Composer may show a warning. The deploy script uses this environment variable to avoid the prompt:

COMPOSER_ALLOW_SUPERUSER=1
Enter fullscreen mode Exit fullscreen mode

A better long-term solution is to use a dedicated deploy user instead of root.

npm ci Fails

The npm ci command requires a package-lock.json file. If your project does not have one, use npm install instead.

You can also generate a lock file locally by running:

npm install
Enter fullscreen mode Exit fullscreen mode

Then commit the generated package-lock.json file.

.ssh/authorized_keys: No such file or directory

Create the .ssh directory and authorized_keys file manually:

mkdir -p ~/.ssh
touch ~/.ssh/authorized_keys
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys
Enter fullscreen mode Exit fullscreen mode

Then add your public key again.

Queue Workers Are Not Using the New Code

Restart Laravel queue workers after deployment:

php artisan queue:restart
Enter fullscreen mode Exit fullscreen mode

If you are using Supervisor, check the worker status:

sudo supervisorctl status
Enter fullscreen mode Exit fullscreen mode

If needed, restart the workers manually:

sudo supervisorctl restart all
Enter fullscreen mode Exit fullscreen mode

GitHub Actions Connects to the Server but Deployment Fails

Check the workflow logs in GitHub Actions. Common causes include:

  • Incorrect app path in the workflow file

  • Missing Composer on the server

  • Missing Node.js or npm on the server

  • Wrong file permissions

  • Failed Laravel migration

  • Failed frontend build

  • Missing environment variables in .env

You can also manually test the deploy command directly on the server:

cd /var/www/your-app
npm run deploy
Enter fullscreen mode Exit fullscreen mode

If it fails manually, fix the server-side issue first before running GitHub Actions again.

Security Recommendations

For a simple personal project, deploying as root may work. However, for production applications, it is better to improve security by following these practices:

  • Use a dedicated deploy user instead of root.

  • Give the deploy user access only to the application directory.

  • Keep your private SSH key only in GitHub Secrets.

  • Do not commit private keys to your repository.

  • Use read-only GitHub deploy keys for pulling code.

  • Make sure your .env file is never committed.

  • Back up your database before running production migrations.

Finally! 😁🫡

You now have a simple automated deployment pipeline for Laravel using GitHub Actions and a DigitalOcean Droplet.

Every time you push to the main branch, GitHub Actions will connect to your server, pull the latest code, install dependencies, build assets, run migrations, optimize Laravel, and restart queue workers.

This setup is a practical starting point for automating Laravel deployments without needing a complex deployment platform. As your application grows, you can improve this workflow further by adding deployment notifications, database backups, test runs, zero-downtime deployment, and rollback support.

If you enjoy this article and would like to show your support, you can easily do so by buying me a coffee. Your contribution is greatly appreciated!

Buy Me A Coffee

Top comments (0)