Klaviyo CI Integration Skill

Klaviyo CI Integration

Overview

Set up a GitHub Actions CI/CD pipeline for Klaviyo integrations: mocked unit tests on every pull request, gated integration tests against the real Klaviyo API on main-branch pushes, SDK-version verification, and an API connectivity smoke test.

The workflow follows the standard two-job split — a fast, key-free unit-tests job safe to require on every PR, and an integration-tests job gated so real-API calls never run on fork PRs where secrets are unavailable.

Prerequisites

GitHub repository with Actions enabled
Klaviyo test API key (from a test/sandbox account)
klaviyo-api SDK and Vitest configured in the repository

Instructions

Step 1: Configure GitHub secrets

Store the Klaviyo test credentials as encrypted repository secrets:

gh secret set KLAVIYO_PRIVATE_KEY --body "pk_test_***"
gh secret set KLAVIYO_WEBHOOK_SIGNING_SECRET --body "whsec_test_***"

Step 2: Add the CI workflow

Create .github/workflows/klaviyo-ci.yml with two jobs. The essential skeleton:

name: Klaviyo Integration CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
jobs:
  unit-tests:        # mocked, runs on every PR, no API key
    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
  integration-tests: # real API, gated to main-branch pushes only
    needs: unit-tests
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    env:
      KLAVIYO_PRIVATE_KEY: ${{ secrets.KLAVIYO_PRIVATE_KEY }}
      KLAVIYO_TEST: '1'
    steps: [...]

The full workflow — including tsc --noEmit, npm list klaviyo-api version check, the connectivity smoke test, and the branch-protection config — is in the CI workflow reference.

Step 3: Write the tests

Author two suites the workflow drives:

Unit tests mock the klaviyo-api SDK (vi.mock) and run with no key.
Integration tests hit the real API behind a describe.skipIf guard keyed on KLAVIYO_TEST + KLAVIYO_PRIVATE_KEY, so they skip cleanly when no key is present.

Full, runnable examples for both suites — event-tracking unit test and a create-and-clean-up live profile test — are in the test examples reference.

Output

Unit tests run on every PR (mocked, no API key needed)
Integration tests run on main-branch pushes only (real API)
SDK version verified in CI via npm list klaviyo-api
API connectivity smoke test included in the integration job

Error Handling

| Issue | Cause | Solution | |-------|-------|----------| | Secret not found in CI | Missing gh secret set | Add the secret via repository settings | | Integration test 429 | Rate limited in CI | Add delays between tests, use a dedicated test key | | Auth failures in CI | Wrong secret name | Verify the secret name matches the workflow env var | | Test timeout | Slow Klaviyo response | Increase timeout-minutes on the job step |

Examples

Set up CI on a fresh repository. Store the test credentials, drop in the workflow, then let the pipeline gate itself:

gh secret set KLAVIYO_PRIVATE_KEY --body "pk_test_***"
# add .github/workflows/klaviyo-ci.yml (see Step 2 skeleton + full reference)
git add .github/workflows/klaviyo-ci.yml && git commit -m "ci: add Klaviyo pipeline"
git push   # opens a PR → unit-tests run mocked; integration-tests stay gated to main

Run the gated integration suite locally before pushing to main:

export KLAVIYO_TEST=1
export KLAVIYO_PRIVATE_KEY="pk_test_***"
npm run test:integration   # skipIf guard now active → live API exercised

Both example flows are expanded — full workflow YAML in references/ci-workflow.md and the complete unit + integration suites in references/test-examples.md.

Resources

Next Steps

For deployment patterns that build on this pipeline, see the klaviyo-deploy-integration skill in this pack.

Agent Skills: Klaviyo CI Integration

Install this agent skill to your local

Skill Files