🦊 SEO Regression Testing in GitLab CI/CD

Add automated SEO quality gates to your GitLab CI/CD pipelines.

GitLab CI/CD pipelines support SEODiff validation as a simple script step. Add it to your deployment stage to block merges with SEO regressions.

Configuration

Copy this configuration into your project:

seo-validation:
  stage: test
  image: curlimages/curl:latest
  variables:
    PREVIEW_URL: "https://$CI_COMMIT_REF_SLUG.preview.example.com"
  script:
    - |
      RESULT=$(curl -s -w "\n%{http_code}" \
        -X POST "https://seodiff.io/api/v1/validate" \
        -H "Authorization: Bearer $SEODIFF_API_KEY" \
        -H "Content-Type: application/json" \
        -d "{\"url\": \"$PREVIEW_URL\", \"wait\": true}")

      HTTP_CODE=$(echo "$RESULT" | tail -1)
      BODY=$(echo "$RESULT" | head -n -1)

      echo "$BODY"

      if [ "$HTTP_CODE" -eq 409 ]; then
        echo "SEO regression detected — blocking merge"
        exit 1
      fi
  only:
    - merge_requests

Setup Steps

Add API key to CI/CD variables

Go to Settings → CI/CD → Variables. Add SEODIFF_API_KEY (masked).

Add the job to .gitlab-ci.yml

Paste the configuration above into your pipeline file in the test stage.

Push a merge request

The job runs on every MR. Pipeline fails if SEODiff detects regressions.

What Gets Checked

The /validate endpoint runs a surface scan and checks for SEO regressions. For deeper testing, combine it with the /agent/evaluate endpoint to add custom assertion rules: