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

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"
}

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"
}

What Each Command Does

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

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

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

/var/www/your-app

For example:

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

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 ""

This will create two files:

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

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"

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

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

Then generate a new SSH key on the Droplet:

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

Print the public key:

cat ~/.ssh/your-app-github.pub

Copy the output, then go to your GitHub repository:

Settings → Deploy keys → Add deploy key

Add the deploy key using these values:

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

Test if the Droplet can connect to GitHub:

ssh -T git@github.com

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

Add the following secrets:

To get the private key contents from your local machine:

Mac or Linux

cat ~/.ssh/your-app-github

Windows PowerShell

cat $env:USERPROFILE\.ssh\your-app-github

Copy everything, including these lines:

-----BEGIN OPENSSH PRIVATE KEY-----
...
-----END OPENSSH PRIVATE KEY-----

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

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

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

It should look like this:

git@github.com:username/repository.git

If it uses HTTPS, update it:

git remote set-url origin git@github.com:username/repository.git

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

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

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

Then add your public key again.

Queue Workers Are Not Using the New Code

Restart Laravel queue workers after deployment:

php artisan queue:restart

If you are using Supervisor, check the worker status:

sudo supervisorctl status

If needed, restart the workers manually:

sudo supervisorctl restart all

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

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.