---

name: elevenlabs-ci-integration description: | Configure CI/CD pipelines for ElevenLabs with mocked unit tests and gated integration tests. Use when setting up GitHub Actions for TTS projects, configuring CI test strategies, or automating ElevenLabs integration validation without burning character quota on every PR. Trigger with "elevenlabs CI", "elevenlabs GitHub Actions", "elevenlabs automated tests", "CI elevenlabs", "elevenlabs pipeline". allowed-tools: Read, Write, Edit, Bash(gh:*) version: 1.6.0 license: MIT author: Jeremy Longshore jeremy@intentsolutions.io tags:

• saas
• voice
• ai
• elevenlabs
• ci
• github-actions compatibility: Designed for Claude Code

---

ElevenLabs CI Integration

Overview

Set up CI/CD pipelines that test ElevenLabs integrations without burning character quota on every PR. Uses a two-tier strategy: mocked unit tests on every push (no API key, zero quota), and gated integration tests that hit the real API only on main or a manual dispatch, behind a quota guard.

The full workflow YAML and secret setup live in references/implementation.md; the complete test code lives in references/examples.md. This file walks the strategy end to end, then drills into either reference for copy-paste source.

Prerequisites

• GitHub repository with Actions enabled
• ElevenLabs API key for integration tests (use a test/dev key, not production)
• npm/pnpm project with vitest configured

Instructions

Step 1: Add the two-tier workflow

Create .github/workflows/elevenlabs-tests.yml with two jobs. unit-tests runs on every push/PR with a mock key. integration-tests runs only on main or workflow_dispatch, needs: unit-tests, and checks remaining quota before spending any:

jobs:
  unit-tests:                       # every push/PR — mock key, 0 quota
    runs-on: ubuntu-latest
    steps: [checkout, setup-node, npm ci, npm test -- --coverage]
    # env: ELEVENLABS_API_KEY: "sk_test_mock_key_for_ci"

  integration-tests:                # main / manual only — real key
    if: github.ref == 'refs/heads/main' || github.event_name == 'workflow_dispatch'
    needs: unit-tests
    # 1) GET /v1/user → skip if remaining characters < 5000
    # 2) npm run test:integration behind that guard

Copy the complete, runnable workflow from references/implementation.md.

Step 2: Store the API key as a repository secret

gh secret set ELEVENLABS_API_KEY --body "sk_your_test_key_here"
# optional, for webhook tests:
gh secret set ELEVENLABS_WEBHOOK_SECRET --body "whsec_your_secret_here"

Step 3: Write mocked unit tests

Mock the entire SDK so unit tests never call the API or spend quota. Minimal skeleton:

vi.mock("@elevenlabs/elevenlabs-js", () => ({
  ElevenLabsClient: vi.fn().mockImplementation(() => ({
    textToSpeech: { convert: vi.fn().mockResolvedValue(/* mock MP3 stream */) },
    voices: { getAll: vi.fn().mockResolvedValue({ voices: [/* Rachel */] }) },
  })),
}));

Full mock (streaming, voices, user/subscription) and assertions: references/examples.md.

Step 4: Write gated integration tests

Skip integration tests unless ELEVENLABS_INTEGRATION is set, and keep them cheap — Flash model, short text, low bitrate:

const SKIP = !process.env.ELEVENLABS_INTEGRATION;
describe.skipIf(SKIP)("ElevenLabs Integration", () => { /* smoke tests */ });

Full smoke suite: references/examples.md.

Step 5: Wire the package scripts

Add test, test:integration, and test:ci scripts so CI and local runs share one entry point. See references/examples.md.

Output

Once configured, the pipeline produces:

• .github/workflows/elevenlabs-tests.yml — two-tier CI pipeline
• ELEVENLABS_API_KEY (and optional webhook secret) stored in GitHub secrets
• tests/unit/ mocked tests that run on every push at 0 character cost
• tests/integration/ smoke tests gated to main/manual behind a quota guard
• npm scripts (test, test:integration, test:ci) shared by CI and local

CI Strategy Summary

Tier	When	API Key	Quota Cost	Coverage
Unit tests	Every push/PR	Mock key	0 characters	SDK integration patterns
Integration	Main + manual	Real test key	~50 chars	End-to-end TTS verification
Quota check	Before integration	Real test key	0 (GET only)	Prevents surprise billing

Error Handling

Issue	Cause	Solution
Secret not found in CI	Missing repository secret	gh secret set ELEVENLABS_API_KEY
Integration tests timeout	Slow TTS generation	Increase test timeout to 30s; use Flash model
Quota depleted in CI	Too many integration runs	Use quota guard; limit to main branch only
Mock drift	SDK API changed	Update mocks when upgrading SDK

Examples

Run only the cheap tier locally (no API key, no quota):

npm test -- --coverage

Trigger the gated integration tier by hand (from the Actions tab or CLI):

gh workflow run elevenlabs-tests.yml

Run integration tests locally against a real test key:

ELEVENLABS_INTEGRATION=1 npm run test:integration

Full worked examples — complete SDK mock, gated smoke suite, and package scripts — are in references/examples.md.

Resources

• references/implementation.md — complete workflow YAML + secret setup
• references/examples.md — complete unit, integration, and package-script code
• GitHub Actions Secrets
• ElevenLabs JS SDK

Next Steps

For deployment patterns, see the elevenlabs-deploy-integration skill, which covers promoting validated TTS builds through staging and production.