XenonFlare

Guides

CI pipeline integration

Gate releases on SEO and GEO health by queuing a crawl from your CI runner, waiting for the job, and failing the build when critical SEO issues or GEO readiness gates are exceeded.

Typical CI gate

Queue a crawl, poll until complete, and fail the workflow when critical issues exceed your threshold.

Overview

CI runners call the same REST endpoints as any integration. Store XF_API_KEY and XF_PROPERTY_ID as encrypted repository secrets. Use a unique Idempotency-Key per pipeline run (for example the commit SHA).

API reference: Developer API.

One-click workflow template

Copy the ready-made workflow for GitHub Actions — includes PR vs main crawl depth and idempotency per run:

Download github-actions-seo-check.yml · GitHub Actions SEO checker landing page

GitHub Actions example (inline)

name: SEO crawl

on:
  push:
    branches: [main]
  pull_request:

jobs:
  seo-check:
    runs-on: ubuntu-latest
    steps:
      - name: Queue XenonFlare scan
        id: queue
        env:
          XF_API_KEY: ${{ secrets.XF_API_KEY }}
          XF_PROPERTY_ID: ${{ secrets.XF_PROPERTY_ID }}
        run: |
          RESP=$(curl -s -X POST \
            -H "Authorization: Bearer $XF_API_KEY" \
            -H "Idempotency-Key: ci-${{ github.sha }}" \
            -H "Content-Type: application/json" \
            -d '{"maxPages": 200, "maxDepth": 4}' \
            https://api.xenonflare.com/api/v1/properties/$XF_PROPERTY_ID/scans)
          echo "job_id=$(echo "$RESP" | jq -r '.data.job.id')" >> $GITHUB_OUTPUT

      - name: Wait for completion
        env:
          XF_API_KEY: ${{ secrets.XF_API_KEY }}
          JOB_ID: ${{ steps.queue.outputs.job_id }}
        run: |
          for i in $(seq 1 40); do
            BODY=$(curl -s -H "Authorization: Bearer $XF_API_KEY" \
              https://api.xenonflare.com/api/v1/jobs/$JOB_ID)
            STATUS=$(echo "$BODY" | jq -r '.data.job.status')
            if [ "$STATUS" = "completed" ]; then exit 0; fi
            if [ "$STATUS" = "failed" ] || [ "$STATUS" = "cancelled" ]; then
              echo "$BODY" | jq .
              exit 1
            fi
            sleep 30
          done
          echo "Timed out waiting for job $JOB_ID"
          exit 1

GEO readiness gates

The downloadable workflow can fail when geoIssuesCount exceeds a repo variable (default 0) or when geoScore is below XF_MIN_GEO_SCORE. This catches missing llms.txt, blocked AI training crawlers, and entity schema gaps before deploy.

Rate limits in CI

Write endpoints are limited per API key (default 60/hour) with an org-wide daily cap. For frequent PR builds, prefer preview crawls with lower maxPages or run full scans on main only.

See rate limits and X-Request-Id for debugging failed steps.

Create an API key

Store your API key as a CI secret and use jobs:write to queue scans on every pull request.

Developer API access requires Starter, Growth, or Agency. Free tier includes the web app and free marketing tools — not API keys.

Create API key in appAPI referenceDeveloper settings →