CI and GitHub Actions setup

Prerequisites

1. Paid plan — CI triggers require API access. View plans and start a free trial if needed.
2. API key — Sign in and create a key on Developers → API keys. Copy it when shown; it cannot be retrieved later.
3. GitHub repository secrets — Add SIGNALDIFF_API_BASE_URL and SIGNALDIFF_CI_API_KEY under Settings → Secrets and variables → Actions.
4. Reachable sitemap — Your workflow needs a public sitemap URL after deploy, or use customer agent routing for internal targets.

Repository secrets

Optional repository variable SIGNALDIFF_DEFAULT_SITEMAP_URL (e.g. https://example.com/sitemap.xml) when you trigger on pull_request without passing sitemap_url in the workflow.

Minimal workflow

Add a workflow file (for example .github/workflows/signal-diff.yml) using funkysi1701/signal-diff-action@v1.9. Run it after your site is reachable.

name: Signal Diff Crawl
on:
  pull_request:
  workflow_dispatch:

jobs:
  crawl:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: funkysi1701/signal-diff-action@v1.9
        with:
          api_base_url: ${{ secrets.SIGNALDIFF_API_BASE_URL }}
          api_key: ${{ secrets.SIGNALDIFF_CI_API_KEY }}
          sitemap_url: https://example.com/sitemap.xml
          fail_mode: error
          comment_on_pr: ${{ github.event_name == 'pull_request' }}
          collect_code_changes: true
          risk_score_enabled: true
          github_token: ${{ github.token }}

Pin a specific release tag (e.g. signal-diff-action@v1.9) in production. See the signal-diff-action README for all inputs, outputs, and advanced options (including inline_annotations).

Fail mode (fail_mode)

The action passes fail_mode to the API. After the crawl completes, the workflow fails when the policy is violated. Crawl execution failures (timeouts, unreachable sitemap) always fail the job regardless of mode.

For pull requests, prefer gating on new findings since the CI baseline—not raw totals alone. See Baselines and diffs.

Automated PR risk analysis

When comment_on_pr: true on pull-request runs, the action posts a decision-focused Signal Diff Report—not a crawl status notification. The report answers “should I merge this?” by combining SEO run-diff results with repository change signals. The same report is appended to the GitHub Actions step summary. Comment failures are best-effort and do not fail the workflow.

Report sections (from signal-diff-action@v1.7 onward):

1. Verdict — pass/fail for your fail_mode plus a severity label (Critical, Warning, Info, Improved, or Compared)
2. Summary table — rule-based risk score (0–10, Low/Medium/High), SEO errors/warnings, new vs resolved findings, files changed, pages crawled
3. Files requiring review — high-attention changed paths (auth, payment, migrations, production config, etc.) with human-readable reasons
4. SEO findings (vs baseline) — headline, impact summary, grouped new findings, baseline before/after counts (separate from repository changes)
5. Repository changes — GitHub compare link and file categorization (code, tests, config, …)
6. Links — Signal Diff scan URL and workflow run

Example output (abbreviated):

## Signal Diff Report

**Verdict:** Pass (fail_mode: error) · Compared

| Metric | Value |
| --- | --- |
| Risk score | Medium (4.2/10) |
| SEO errors | 0 |
| SEO warnings | 2 |
| New findings | 0 |
| Resolved | 1 |
| Files changed | 10 |
| Pages crawled | 24 |

### Files requiring review
- src/Auth/JwtProvider.cs — security-sensitive area

### SEO findings (vs baseline)
No new run-diff findings vs baseline. Baseline: 12 findings → current: 12.

### Repository changes
10 files changed (code: 8, tests: 1, config: 1)

Optional inputs (see the signal-diff-action README for defaults and full reference):

SEO URL findings are not mapped to repository lines—use the summary comment and scan link for on-site regressions. Inline annotations cover repository paths only (auth, payment, migrations, production config, etc.).

Permissions:

• pull-requests: write — required when comment_on_pr or inline_annotations is enabled
• contents: read — required for GitHub Compare and the code-change summary attached to the job

permissions:
  contents: read
  pull-requests: write

Agent routing in CI

Targets only reachable from your network (staging behind VPN, internal hosts) should use a customer agent instead of the default cloud crawl. Pass these action inputs (enroll agents on Customer agents first):

• execution_mode: agent
• agent_pool_id: production (must match the pool on your enrolled agent)

- uses: funkysi1701/signal-diff-action@v1.9
  with:
    api_base_url: ${{ secrets.SIGNALDIFF_API_BASE_URL }}
    api_key: ${{ secrets.SIGNALDIFF_CI_API_KEY }}
    sitemap_url: https://internal.example/sitemap.xml
    fail_mode: error
    execution_mode: agent
    agent_pool_id: production

Where to see results

• Signal Diff dashboard — Full report at /scan/{jobId}; trigger shows as CI with repository, commit, branch, and pull request context when supplied.
• GitHub Actions — Workflow logs and optional PR risk report comment.
• Run diff — Compare against the prior CI run on the same repository and sitemap when available. See Baselines and diffs.

Troubleshooting

More edge cases (WAF, health checks, webhooks, self-hosted Trigger:CiApiKey) are in the repository guide docs/github-action-seo-crawler-setup.md. See also the consolidated Troubleshooting guide.