perplexity-ci-integration

Perplexity CI Integration

Overview

Set up CI/CD pipelines for Perplexity Sonar API integrations. Key CI concerns: live API calls cost money (use mocks for unit tests, reserve live calls for integration tests), API keys must be in GitHub Secrets, and rate limits apply even in CI.

Prerequisites

• GitHub repository with Actions enabled
• Perplexity API key for CI (separate from production)
• Test suite with mocked and live test separation

Instructions

Step 1: Configure GitHub Secret

set -euo pipefail
# Store API key as a GitHub secret
gh secret set PERPLEXITY_API_KEY --body "pplx-your-ci-key-here"

Step 2: GitHub Actions Workflow

# .github/workflows/perplexity-tests.yml
name: Perplexity Integration Tests

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"
      - run: npm ci
      - run: npm test -- --coverage
        # Unit tests use mocked responses — no API key needed

  integration-tests:
    runs-on: ubuntu-latest
    needs: unit-tests
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    env:
      PERPLEXITY_API_KEY: ${{ secrets.PERPLEXITY_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"
      - run: npm ci
      - name: Run live Perplexity integration tests
        run: npm run test:integration
        timeout-minutes: 5

Step 3: Test Structure

// tests/perplexity.unit.test.ts — runs on every PR, uses mocks
import { describe, it, expect, vi } from "vitest";
import fixture from "./fixtures/sonar-response.json";

vi.mock("openai", () => ({
  default: vi.fn().mockImplementation(() => ({
    chat: {
      completions: {
        create: vi.fn().mockResolvedValue(fixture),
      },
    },
  })),
}));

describe("Perplexity Search (mocked)", () => {
  it("parses citations from response", async () => {
    const { search } = await import("../src/perplexity/search");
    const result = await search("test query");
    expect(result.citations.length).toBeGreaterThan(0);
  });

  it("formats answer with citation links", async () => {
    const { formatCitationsAsMarkdown } = await import("../src/perplexity/citations");
    const formatted = formatCitationsAsMarkdown("See [1] for details", ["https://example.com"]);
    expect(formatted).toContain("[1](https://example.com)");
  });
});

// tests/perplexity.integration.test.ts — runs on main only, uses live API
import { describe, it, expect } from "vitest";

const LIVE = !!process.env.PERPLEXITY_API_KEY;

describe.skipIf(!LIVE)("Perplexity Live API", () => {
  it("sonar returns answer with citations", async () => {
    const { search } = await import("../src/perplexity/search");
    const result = await search("What is TypeScript?", {
      model: "sonar",
      maxTokens: 100,
    });

    expect(result.answer).toBeTruthy();
    expect(result.citations.length).toBeGreaterThan(0);
    expect(result.usage.totalTokens).toBeGreaterThan(0);
  }, 15000);

  it("search_domain_filter restricts sources", async () => {
    const { search } = await import("../src/perplexity/search");
    const result = await search("Python latest release", {
      model: "sonar",
      maxTokens: 100,
      searchDomainFilter: ["python.org"],
    });

    expect(result.citations.some((url: string) => url.includes("python.org"))).toBe(true);
  }, 15000);
});

Step 4: Cost-Aware CI

# Only run live tests on main branch pushes (not every PR)
# Budget: ~$0.01 per test run (2 sonar queries at $0.005 each)
# Monthly estimate: 30 pushes/month = $0.30

# Add a weekly full integration test
  weekly-integration:
    runs-on: ubuntu-latest
    if: github.event.schedule == '0 6 * * 1'
    env:
      PERPLEXITY_API_KEY: ${{ secrets.PERPLEXITY_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: npm ci
      - run: npm run test:integration:full
        timeout-minutes: 10

Error Handling

Issue	Cause	Solution
Secret not found	Missing GitHub secret	Run gh secret set PERPLEXITY_API_KEY
Integration tests timeout	Complex sonar-pro queries	Use sonar with max_tokens: 100 in CI
429 in CI	Parallel jobs hitting rate limit	Serialize integration tests
High CI costs	Running live tests on every PR	Gate live tests on main branch only

Output

• Unit test suite with mocked Perplexity responses (runs on every PR)
• Integration test suite with live API (runs on main pushes)
• Cost-optimized CI that limits API calls
• GitHub Actions workflow file

Resources

• GitHub Actions Documentation
• Vitest Documentation

Next Steps

For deployment patterns, see perplexity-deploy-integration.