aiseo-auditv2.0.1

Documentation

aiseo-audit continuous integration and GitHub Action

In brief. This is the aiseo-audit GitHub Action for running a repeatable AI SEO audit during continuous integration. It checks preview or production URLs, enforces a calibrated score threshold, and updates one pull-request comment with the result.

Maintained by Jeff Patterson and Agency Enterprise · Updated August 30, 2026

How the aiseo-audit GitHub Action works: overview

The action is the continuous integration interface for checking an accessible page before code is merged.

A workflow supplies the URL, optional target queries, and a score threshold. The action runs the audit and returns a pass or fail exit code.

The baseline comes first because an arbitrary threshold rewards score chasing instead of regression detection. This means version, queries, and page profile must stay stable across compared runs.

aiseo-audit continuous integration and GitHub Action terms

Continuous integration

Continuous integration refers to automated checks that run when code changes.

GitHub Action

A GitHub Action refers to the packaged audit step used in a GitHub workflow.

Preview URL

A preview URL means that the deployment under review is publicly reachable by the audit job.

Quality threshold

A quality threshold is defined as the minimum accepted score passed to fail-under.

Pull-request comment

A pull-request comment refers to the single updated summary posted by the action.

Regression

A regression is a type of measured decline from a saved and comparable baseline.

GitHub Action

Set comment-on-pr to true to keep one pull-request comment with the score, grade, stages, and top recommendations.

name: AI SEO Audit
on: pull_request

jobs:
  audit:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: agencyenterprise/aiseo-audit@v2
        with:
          url: https://your-preview-url.example
          fail-under: 70
          comment-on-pr: true

One-line quality gate

npx aiseo-audit https://your-preview-url.example --fail-under 70

Establish a baseline first

Audit representative pages with the same queries and profiles before blocking a release. Version 2 scores cannot be compared with version 1 scores. Set new thresholds when moving the action from @v1 to @v2.

How to use this reference

  1. Deploy the page to an address the workflow can reach.
  2. Record a baseline with stable queries and a stable major version.
  3. Set the threshold below the baseline by the accepted tolerance.
  4. Run the action on pull requests.
  5. Review the changed factors before changing the threshold.

Key takeaways

  • The action is a regression check for reachable web pages.
  • The baseline is required before a threshold has project meaning.
  • The exit code is zero when the configured gate passes.
  • The pull-request comment is updated instead of posted again.
  • The major version is part of every valid score comparison.

Bottom line: Calibrate the baseline first, then use the action to catch meaningful page regressions.

Official sources and verification

According to the npm package page, aiseo-audit publishes its current version and installation command [1]. According to the GitHub repository, the source code and project documentation are public [2].

According to the evidence map, every scored factor records an evidence tier and pipeline stage [3]. According to the release history, major versions document scoring changes that require new baselines [4]. According to the project license, aiseo-audit uses the MIT license[5].

  1. aiseo-audit on npm: package, version, and installation details.
  2. agencyenterprise/aiseo-audit: source code and documentation.
  3. aiseo-audit evidence map: factor tiers, stages, and research sources.
  4. aiseo-audit releases: version history and migration notes.
  5. MIT license: project license text.