GitLab CI/CD

Run Aulys accessibility scans as a GitLab CI job to block merge requests that introduce new violations.

Prerequisites

An Aulys API key from app.aulys.app → Settings → API Keys
A GitLab project with CI/CD enabled
A staging or review app URL reachable from GitLab runners

Add API key as a CI/CD variable

In GitLab, go to Settings → CI/CD → Variables and add:

Key

AULYS_API_KEY

Type

Variable (masked)

Check Mask variable so the value is never exposed in job logs.

Add the accessibility job to .gitlab-ci.yml

.gitlab-ci.yml

stages:
  - test
  - accessibility

accessibility-check:
  stage: accessibility
  image: curlimages/curl:latest
  only:
    - merge_requests
    - main
  script:
    # Trigger a scan via the Aulys API
    - |
      SCAN_RESPONSE=$(curl -s -X POST https://api.aulys.app/v1/scans \
        -H "Authorization: Bearer $AULYS_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "url": "'"$STAGING_URL"'",
          "wcagVersion": "2.2",
          "wcagLevel": "AA"
        }')
      SCAN_ID=$(echo $SCAN_RESPONSE | grep -o '"id":"[^"]*"' | head -1 | cut -d'"' -f4)
      echo "Scan ID: $SCAN_ID"

    # Poll for results (max 60 seconds)
    - |
      for i in $(seq 1 12); do
        sleep 5
        STATUS=$(curl -s \
          -H "Authorization: Bearer $AULYS_API_KEY" \
          "https://api.aulys.app/v1/scans/$SCAN_ID" \
          | grep -o '"status":"[^"]*"' | cut -d'"' -f4)
        echo "Status: $STATUS"
        if [ "$STATUS" = "completed" ]; then break; fi
      done

    # Fetch results and fail if critical violations found
    - |
      RESULT=$(curl -s \
        -H "Authorization: Bearer $AULYS_API_KEY" \
        "https://api.aulys.app/v1/scans/$SCAN_ID")
      CRITICAL=$(echo $RESULT | grep -o '"critical":[0-9]*' | cut -d':' -f2)
      echo "Critical violations: $CRITICAL"
      if [ "$CRITICAL" -gt "0" ]; then
        echo "FAILED: $CRITICAL critical accessibility violations found"
        exit 1
      fi
      echo "PASSED: No critical violations"

  artifacts:
    when: always
    reports:
      # Save the scan URL so it appears in the MR widget
      dotenv: aulys.env

Using GitLab Review Apps

If you have Dynamic Environments or Review Apps configured, you can scan the environment URL automatically:

With Review Apps

accessibility-check:
  stage: accessibility
  needs: ["deploy-review"]  # wait for review app to deploy
  environment:
    name: review/$CI_COMMIT_REF_SLUG
  variables:
    STAGING_URL: $CI_ENVIRONMENT_URL
  script:
    # ... same as above, $STAGING_URL is now the review app URL
    - echo "Scanning $STAGING_URL"

Troubleshooting

"curl: command not found"

Change the image to curlimages/curl:latest or install curl with apk add curl / apt-get install -y curl in your base image.

SCAN_ID is empty

The API call may be failing silently. Add -v to curl to see verbose output and check for authentication errors. Verify AULYS_API_KEY is masked but not protected-only.

Job always passes even with violations

The grep pattern for "critical" must match exactly. Use jq instead: CRITICAL=$(echo $RESULT | jq ".summary.critical") for reliable JSON parsing.

Related guides

GitHub Actions

Same workflow for GitHub Actions.

Read

API Reference

Full REST API documentation.

Read

stages: - test - accessibility accessibility-check: stage: accessibility image: curlimages/curl:latest only: - merge_requests - main script: # Trigger a scan via the Aulys API - | SCAN_RESPONSE=$(curl -s -X POST https://api.aulys.app/v1/scans \ -H "Authorization: Bearer $AULYS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "'"$STAGING_URL"'", "wcagVersion": "2.2", "wcagLevel": "AA" }') SCAN_ID=$(echo $SCAN_RESPONSE | grep -o '"id":"[^"]*"' | head -1 | cut -d'"' -f4) echo "Scan ID: $SCAN_ID" # Poll for results (max 60 seconds) - | for i in $(seq 1 12); do sleep 5 STATUS=$(curl -s \ -H "Authorization: Bearer $AULYS_API_KEY" \ "https://api.aulys.app/v1/scans/$SCAN_ID" \ | grep -o '"status":"[^"]*"' | cut -d'"' -f4) echo "Status: $STATUS" if [ "$STATUS" = "completed" ]; then break; fi done # Fetch results and fail if critical violations found - | RESULT=$(curl -s \ -H "Authorization: Bearer $AULYS_API_KEY" \ "https://api.aulys.app/v1/scans/$SCAN_ID") CRITICAL=$(echo $RESULT | grep -o '"critical":[0-9]*' | cut -d':' -f2) echo "Critical violations: $CRITICAL" if [ "$CRITICAL" -gt "0" ]; then echo "FAILED: $CRITICAL critical accessibility violations found" exit 1 fi echo "PASSED: No critical violations" artifacts: when: always reports: # Save the scan URL so it appears in the MR widget dotenv: aulys.env

accessibility-check: stage: accessibility needs: ["deploy-review"] # wait for review app to deploy environment: name: review/$CI_COMMIT_REF_SLUG variables: STAGING_URL: $CI_ENVIRONMENT_URL script: # ... same as above, $STAGING_URL is now the review app URL - echo "Scanning $STAGING_URL"

Troubleshooting

"curl: command not found"

Change the image to curlimages/curl:latest or install curl with apk add curl / apt-get install -y curl in your base image.

SCAN_ID is empty

The API call may be failing silently. Add -v to curl to see verbose output and check for authentication errors. Verify AULYS_API_KEY is masked but not protected-only.

Job always passes even with violations

The grep pattern for "critical" must match exactly. Use jq instead: CRITICAL=$(echo $RESULT | jq ".summary.critical") for reliable JSON parsing.