Guide to Configuring CI/CD on GitLab with .gitlab-ci.yml for Web Projects

Introduction to CI/CD on GitLab

CI/CD (Continuous Integration/Continuous Deployment) is a critical automation process in software development, helping to minimize errors and accelerate application deployment. With GitLab, you can easily configure CI/CD using the .gitlab-ci.yml file. This article provides a detailed guide on how to use the .gitlab-ci.yml file to build, test, and deploy web projects, leveraging DDEV and Drush, with demo domains such as demo.app, demo.edu.vn, and multi-platform sites.

The .gitlab-ci.yml file below is a practical example, optimized to automate the build, pre-deployment testing (pre-deploy), and deployment (deploy) stages for Drupal or similar web projects.

Why Configure CI/CD on GitLab?

Configuring CI/CD on GitLab offers numerous benefits:

• Automation: Automatically execute build, test, and deploy commands, saving time compared to manual processes.
• Reliability: Detect issues early through code and website status checks before deployment.
• Flexibility: Support deployment across multiple environments (staging, production) with domains like demo.app or demo.edu.vn.
• Powerful Integration: Seamlessly integrate with tools like Composer, Drush, and DDEV for efficient Drupal project management.

Detailed Configuration of the .gitlab-ci.yml File

Below is an explanation of each section in the .gitlab-ci.yml file, with IPs/domains replaced with "demo":

Defining Stages

stages:
  - build
  - pre_deploy
  - deploy

The file defines 3 stages:

• Build: Constructs the project, installs dependencies, and performs basic functionality checks.
• Pre_deploy: Conducts pre-deployment checks to ensure no uncommitted changes exist.
• Deploy: Deploys to servers with domains like demo.app.

Build Stage

build:
  stage: build
  only:
    - main
  allow_failure: false
  before_script:
    - echo "🚀 Starting DDEV..."
    - ddev start
  script:
    - echo "🚀 Running composer install in DDEV..."
    - ddev composer install --optimize-autoloader
    - echo "Modifying settings.php to use config sync directory..."
    - SETTINGS_FILE="web/sites/default/settings.php"
    - CONFIG_LINE="\$settings['config_sync_directory'] = '../config/sync';"
    - grep -qF "$CONFIG_LINE" "$SETTINGS_FILE" || echo "$CONFIG_LINE" >> "$SETTINGS_FILE"
    - echo "🔁 Importing site configuration with Drush..."
    - ddev drush cr
    - ddev drush cim -y
    - ddev drush updb -y
    - ddev drush upe -y
    - ddev drush cr
    - echo "🔎 Checking the website at http://demo.ddev.site..."
    - ddev exec curl http://demo.ddev.site/
    - |
      response=$(ddev exec curl -o /dev/null -s -w "%{http_code}" -L http://demo.ddev.site)
      echo "response code: $response"
      if [ "$response" -eq 200 ]; then
        echo "✅ Website is operational!"
      else
        echo "❌ ERROR: Website is inaccessible! HTTP_CODE=$response"
        exit 1
      fi

Functionality:

• Starts DDEV and installs dependencies with Composer.
• Configures settings.php for Drupal config synchronization.
• Runs Drush commands (cim, updb, upe) to import configurations, update the database, and export content.
• Tests the website at http://demo.ddev.site, failing the pipeline if the HTTP code isn’t 200.

Pre_deploy Stage

check_production_changes:
  stage: pre_deploy
  when: manual
  needs:
    - build
  allow_failure: false
  only:
    - main
  script:
    - echo "🚀 Deploying to demo.app..."
    - ssh -o StrictHostKeyChecking=no root@demo "
      cd /home/iotdev/vn-ielts-test &&
      CURRENT_BRANCH=\$(git rev-parse --abbrev-ref HEAD) &&
      echo '🔍 Current branch '$CURRENT_BRANCH &&
      if [ \"\$CURRENT_BRANCH\" != \"$CI_COMMIT_REF_NAME\" ]; then
      echo '❌ ERROR Branch mismatch! Expected '$CI_COMMIT_REF_NAME' but found '\$CURRENT_BRANCH &&
      exit 1;
      fi &&
      echo '✅ Branch check passed. Proceeding with export configs...' &&
      vendor/bin/drush cex -y &&
      if [ -n \"\$(git diff --name-only)\" ]; then
      echo '❌ ERROR Uncommitted changes detected! Please commit or stash changes before deployment.' &&
      git status &&
      exit 1;
      fi &&
      if [ -n \"\$(git ls-files --others --exclude-standard)\" ]; then
      echo '❌ ERROR Untracked files detected! Please commit or remove them before deployment.' &&
      git status &&
      exit 1;
      fi &&
      echo '✅ No uncommitted changes and no untracked files. Proceeding with deployment...'
      "
    - echo "==================================="
    - echo "🚀 Deploying to demo.edu.vn..."
    - ssh -o StrictHostKeyChecking=no root@demo "
      cd /home/iotdev/vn-ielts-test &&
      # (Similar branch and config checks as above)
      "
    - echo "==================================="
    - echo "🚀 Deploying to Multiple sites demo-site1.edu.vn, demo-site2.org, demo-site3.edu.vn..."
    - ssh -o StrictHostKeyChecking=no root@demo "
      cd /home/iotdev/vn-ielts-test &&
      # (Branch checks and config exports for each site)
      "
    

Functionality:

• Verifies that the current branch matches main.
• Exports configs with Drush (cex) and checks for uncommitted changes or untracked files.
• Applies to multiple demo domains like demo.app, demo.edu.vn, and multi-platform sites.

Deploy Stage

deploy:
  stage: deploy
  when: manual
  needs:
    - check_production_changes
  allow_failure: false
  only:
    - main
  script:
    - echo "🚀 Deploying to demo.app..."
    - ssh -o StrictHostKeyChecking=no root@demo "
      cd /home/iotdev/vn-ielts-test &&
      CURRENT_BRANCH=\$(git rev-parse --abbrev-ref HEAD) &&
      if [ \"\$CURRENT_BRANCH\" != \"$CI_COMMIT_REF_NAME\" ]; then
      echo '❌ ERROR Branch mismatch!' && exit 1;
      fi &&
      echo '✅ Branch check passed. Proceeding with deployment...' &&
      vendor/bin/drush state:set system.maintenance_mode 1 &&
      git pull && composer install --optimize-autoloader &&
      vendor/bin/drush cr &&
      vendor/bin/drush cim -y &&
      vendor/bin/drush updb -y &&
      vendor/bin/drush upe -y &&
      vendor/bin/drush state:set system.maintenance_mode 0 &&
      vendor/bin/drush cr
      "
    - echo "==================================="
    - echo "🚀 Deploying to demo.edu.vn..."
    - ssh -o StrictHostKeyChecking=no root@demo "
      # (Similar deployment process for demo.edu.vn)
      "
    - echo "==================================="
    - echo "🚀 Deploying to Multiple sites demo-site1.edu.vn, demo-site2.org, demo-site3.edu.vn..."
    - ssh -o StrictHostKeyChecking=no root@demo "
      # (Deployment for each site with Drush multi-site commands)
      "
    

Functionality:

• Switches the website to maintenance mode.
• Pulls code from Git, installs Composer dependencies, and runs Drush commands to update configurations and the database.
• Disables maintenance mode and verifies the site.

How to Set Up CI/CD with GitLab

1. Create the .gitlab-ci.yml File: Copy the content above and place it in the root directory of your GitLab project.
2. Configure a Runner: Ensure a GitLab Runner is installed on the demo server with DDEV and Drush support.
3. Run the Pipeline: Push code to the main branch, then monitor the pipeline in the CI/CD tab of GitLab.
4. Check Results: Review the logs to confirm each stage (build, pre_deploy, deploy) completes successfully.

Benefits of This Configuration

• Time Optimization: Automates the entire process from build to deployment.
• Quality Assurance: Detects errors before deploying to production environments like demo.app.
• Multi-site Support: Easily deploys to multiple demo domains with a single configuration file.

Call to Action

Start implementing this CI/CD configuration on GitLab today to streamline your web project development process! Learn more about GitLab CI/CD in the official documentation and begin automating now!