For developers

Validate UCP + ACP readiness in CI/CD

Stop shipping broken profiles. A single missing field or a namespace mismatch can make your store invisible to AI shopping agents — and it passes JSON.parse() just fine. Add UCP validation to your pipeline and catch it on every push, with a published GitHub Action and the @ucptools/validator npm CLI.

GitHub Actions GitLab CI CircleCI npx / any runner

GitHub Actions

The fastest path on GitHub. The action calls the UCPtools API to run 4-level validation and returns an AI readiness score. Add it to any workflow:

name: UCP Validation
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: Nolpak14/ucp-validate-action@v1
        with:
          domain: 'yourstore.com'

Gate the build on a threshold

By default the action is informational. Add fail-on-grade and/or fail-on-score to turn it into a quality gate, and it will post the breakdown as a PR comment:

name: UCP Validation
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: Nolpak14/ucp-validate-action@v1
        with:
          domain: 'yourstore.com'
          fail-on-grade: 'C'   # fail the build on grade C or worse
          fail-on-score: '70'  # ...or if the score drops below 70
          comment: 'true'      # post the full breakdown as a PR comment

Block a deploy on staging validation

The pattern that matters most: validate your staging profile before the production deploy job is allowed to run.

name: Deploy
on:
  push:
    branches: [main]

jobs:
  validate-ucp:
    runs-on: ubuntu-latest
    steps:
      - uses: Nolpak14/ucp-validate-action@v1
        with:
          domain: 'staging.yourstore.com'
          fail-on-grade: 'C'

  deploy:
    needs: validate-ucp   # deploy only runs if validation passes
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying to production..."

Inputs: domain (required), fail-on-grade, fail-on-score, comment. Outputs: score, grade, ucp-found, passed, result-json. Full reference on the action repo.

GitLab CI

No GitHub dependency — run the CLI on any Node image. The command exits non-zero when validation fails, which fails the job. Add this to your .gitlab-ci.yml:

ucp-validation:
  image: node:20-alpine
  script:
    - npx -p @ucptools/validator ucp-validate validate --remote yourstore.com
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == "main"

CircleCI

Same CLI, dropped into a CircleCI job. Add this to .circleci/config.yml:

version: 2.1

jobs:
  ucp-validation:
    docker:
      - image: cimg/node:20.11
    steps:
      - run:
          name: Validate UCP profile
          command: npx -p @ucptools/validator ucp-validate validate --remote yourstore.com

workflows:
  validate:
    jobs:
      - ucp-validation

npx / any runner

The @ucptools/validator CLI runs anywhere Node.js 20+ is available — Jenkins, Bitbucket Pipelines, a Makefile, or a local pre-commit hook. It exits non-zero on a failing profile.

# One-off remote check — exits non-zero if validation fails (fails the job)
npx -p @ucptools/validator ucp-validate validate --remote yourstore.com

# Validate a local profile file before you deploy it
npx -p @ucptools/validator ucp-validate validate --file ./public/.well-known/ucp

# JSON output, for custom gating in a script
npx -p @ucptools/validator ucp-validate validate --remote yourstore.com --json

Wire it into your test suite

Install it as a dev dependency and expose an npm script so any CI that runs your tests also checks UCP:

# Install once as a dev dependency
npm install --save-dev @ucptools/validator

# package.json
{
  "scripts": {
    "test:ucp": "ucp-validate validate --remote yourstore.com"
  }
}

# Now any CI that runs your test step catches UCP regressions
npm run test:ucp

Grading scale

Scores are a composite of UCP profile validity, Schema.org quality, and endpoint performance. Use them to pick a sensible fail-on-grade / fail-on-score bar.

Grade	Score	Meaning
A	90–100	AI Commerce Ready
B	75–89	AI Optimized
C	60–74	AI Discoverable
D	40–59	Needs Work
F	0–39	Not Ready

FAQ

How do I validate UCP in CI/CD?

On GitHub, add the published Nolpak14/ucp-validate-action@v1 GitHub Action to a workflow and point it at your domain — it runs 4-level UCP validation, scores AI readiness, and can fail the build on a grade or score threshold. On any other CI (GitLab, CircleCI, Jenkins, etc.), run the @ucptools/validator npm CLI with "npx -p @ucptools/validator ucp-validate validate --remote yourstore.com", which exits non-zero when validation fails.

Does the GitHub Action post PR comments?

Yes. On pull requests the ucp-validate-action posts (and updates in place) a comment with the AI readiness score, grade, a category breakdown for UCP / Schema.org / Performance, and any validation issues with error codes. Set comment: "false" to disable it and use step summaries only.

Can I fail the build when readiness drops?

Yes. The GitHub Action supports fail-on-grade (A/B/C/D/F) and fail-on-score (0-100) — either condition failing fails the build. The @ucptools/validator CLI exits with a non-zero code whenever the profile fails validation, which fails the job on any CI runner.

What if I do not use GitHub?

Use the @ucptools/validator CLI directly. It runs on any Node.js 20+ runner via npx, so it drops into GitLab CI, CircleCI, Jenkins, Bitbucket Pipelines, or a local pre-commit hook without a GitHub dependency.

Not sure what your score is yet?

Run a free readiness check on any domain first, then drop the right threshold into your pipeline.

Check any domain free →GitHub Action →