gabrielmoreira 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-apiSDK 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-apiSDK (vi.mock) and run with no key. - Integration tests hit the real API behind a
describe.skipIfguard keyed onKLAVIYO_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
- GitHub Actions documentation
- GitHub encrypted secrets
- Full CI workflow reference
- Test examples reference
Next Steps
For deployment patterns that build on this pipeline, see the
klaviyo-deploy-integration skill in this pack.