SEO GitHub Action: Fail the Build on SEO Regressions

Example Workflow

Add the API key as the repository secret QUIKSEO_API_KEY, then build the site and run the action on the output directory.

name: SEO check
on:
  pull_request:
  push:
    branches: [main]

jobs:
  quikseo:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build
      # OWNER/REPOSITORY is the repository that holds the QuikSEO action, REF a tag or commit of it
      - uses: OWNER/REPOSITORY/packages/action@REF
        with:
          directory: dist
          base-url: https://example.com
          api-key: ${{ secrets.QUIKSEO_API_KEY }}
          baseline-branch: main
          deploy: ${{ github.ref == 'refs/heads/main' }}

Pull Requests and the Production Branch

The same step serves both: it compares a pull request with the production branch and records each production deploy.

On a Pull Request

With baseline-branch: main, a finding is new when the latest check of main does not have it. Only new findings at or above threshold fail the job, so existing problems do not block unrelated work.

On the Production Branch

Each check of main becomes the baseline of later pull requests. With deploy: true, the action records the deploy and re-audits the monitored URLs, so a problem that appears live is attributed to the right commit.

Comparing a Preview Deployment

Set preview-origin to a verified preview origin to audit the build's pages on the preview and on production; new findings on the preview fail the job.

Inputs

Only directory, base-url and api-key are required.

Related Documentation

• QuikSEO CLI for build checks
• Site contract for SEO conventions