Automatically Deploying Drupal Projects with GitHub Actions (Modules, Themes & Config)

When working with Drupal, deployment goes beyond simply uploading modules or themes. Unlike other CMS platforms, Drupal relies heavily on configuration management, Composer dependencies, and database updates.

In this guide, I'll show you how to automatically deploy a Drupal project using GitHub Actions, including custom modules, themes, and configuration changes.

Understanding Drupal Deployment

Before jumping into automation, it's important to understand how Drupal handles deployments.

A Drupal application consists of:

• Codebase (modules, themes, core)
• Dependencies (managed via Composer)
• Configuration (stored in /config/sync)
• Database updates

This means deployment is not just copying files, it's a controlled process that ensures consistency across environments.

Project Structure

A typical Drupal project looks like this:

/web
  /modules/custom
  /themes/custom
/config/sync
composer.json

Our custom work (modules/themes) lives inside /web, but everything is orchestrated through Composer and configuration management.

GitHub Actions Workflow

Below is a basic GitHub Actions pipeline to deploy a Drupal project:

name: Deploy Drupal

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: 8.1

      - name: Install dependencies
        run: composer install --no-dev --optimize-autoloader

      - name: Deploy files to server
        run: |
          rsync -avz --delete ./ user@your-server:/var/www/drupal-project

      - name: Run Drupal commands
        run: |
          ssh user@your-server "
            cd /var/www/drupal-project &&
            drush cim -y &&
            drush updb -y &&
            drush cr
          "

What Happens During Deployment

Each deployment executes three critical steps:

1. Import Configuration

drush cim -y

Syncs configuration changes (content types, fields, views, etc.)

2. Run Database Updates

drush updb -y

Applies pending schema changes from modules

3. Clear Cache

drush cr

Ensures Drupal reflects the latest changes

Key Differences from WordPress

If you're coming from WordPress, like me when I started in Drupal, the biggest mindset shift is this:

• You don’t deploy just a plugin
• You deploy the entire application state

This, in my opniion, makes Drupal deployments more predictable, but also more structured.

Deploying Only a Custom Module - Optional

While not recommended for production workflows, we can deploy only a module:

/web/modules/custom/your_module

However, westill need to clear cache:

drush cr

For a more robust approach, managing our module as a Composer package looks a better choice.

Best Practices

• Always version your /config/sync directory
• Never edit configuration directly in production
• Use Composer for dependency management
• Automate Drush commands in your pipeline
• Treat Drupal as a full application, not just a CMS

Automating Drupal deployments with GitHub Actions provides a reliable and repeatable workflow. By combining Composer, configuration management, and Drush, we can ensure that every environment stays in sync.

While this approach may feel more complex compared to other CMS platforms, it offers significantly more control and scalability, especially in team environments and production systems.

If you're already automating WordPress deployments, adopting this workflow for Drupal is a natural next step toward more advanced DevOps practices.