---

name: serpapi-ci-integration description: 'Gate SerpAPI code with sanitized fixtures and isolate optional live searches behind trusted CI environments and allowance controls. Use when adding integration tests to automation. Trigger with "add SerpAPI CI".' argument-hint: "[github-actions|other-ci] [python|javascript]" allowed-tools: Read, Glob, Grep, WebFetch, Write, Edit, Bash(gh:*) version: 1.6.0 author: Jeremy Longshore jeremy@intentsolutions.io license: MIT tags: [saas, serpapi, ci, testing, github-actions] model: inherit effort: high compatibility: Designed for Claude Code; CI secret and workflow changes require repository approval, and fork pull requests must never receive the SerpAPI key

SerpAPI Fixture-First CI Integration

Overview

Make parsing and policy gates deterministic on every change while restricting live search to a separately approved, trusted workflow.

Prerequisites

• Sanitized fixtures and an injected client boundary
• Repository CI conventions, required checks, and fork threat model
• A protected environment, allowance budget, and owner for any live smoke test

Tool Discipline

Use Read, Glob, and Grep to inspect tests and workflows, WebFetch to verify current client behavior, Write or Edit for fixtures, tests, and CI, and Bash(gh:*) only to inspect or operate the approved GitHub workflow.

Current Contract

Offline fixture tests require no SerpAPI credential or search allowance. A live search is external, variable, and potentially billable; untrusted pull-request code must not receive SERPAPI_KEY, including through unsafe workflow-trigger patterns.

Authentication

Store SERPAPI_KEY only in a protected CI environment. Never expose it to fork PRs, logs, artifacts, command traces, caches, or fixture updates. Give live jobs read-only repository permissions unless a documented need proves otherwise.

Instructions

1. Inventory CI triggers, fork behavior, permissions, secret scopes, environments, artifacts, and dependency installation.
2. Put parser, adapter, error, pagination, redaction, and policy tests on sanitized fixtures with network disabled.
3. Run fixture tests on every pull request and push using pinned actions and locked dependencies.
4. Define an optional live smoke job on a manual, scheduled, or trusted-main trigger; bind it to a protected environment and explicit concurrency/search budget.
5. Check account capacity first, execute one harmless request, and emit only status, search ID, and safe counts.
6. Make live failure diagnostically visible but decide deliberately whether it is required or advisory; never let provider variance weaken deterministic gates.
7. Test a fork PR path, secret redaction, cancellation, timeout, allowance exhaustion, and artifact contents before enabling the job.

Approval Boundaries

Do not add secrets, approve a fork workflow, change required checks, or enable allowance-consuming schedules without repository and account-owner approval.

Output

Return the trigger/permission matrix, fixture test results, live-job boundary and budget, secret-flow proof, fork test evidence, required/advisory decision, and rollback owner.

Error Handling

Condition	Response
Fork code can reach the secret	Block the workflow and redesign the event boundary.
Fixture job attempts network	Fail CI and replace the client dependency.
Live check returns 429	Stop the job and classify throughput versus allowance via Account API.
Provider is unavailable	Preserve deterministic gates and report the live lane separately.

Example

permissions:
  contents: read

jobs:
  fixture-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: python -m pip install -r requirements.lock
      - run: python -m pytest tests/serpapi -q

Resources

• GitHub Actions security hardening
• Official Python client
• Account API

Next Steps

Exercise the fork path and protected live lane, then document which evidence is release-blocking.