---
name: jeremylongshore/klaviyo-ci-integration
source: https://app.decimal.ai/s/jeremylongshore-klaviyo-ci-integration@1/SKILL.md
source_sha256: f840196e2d48
---

# 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:

```bash
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:

```yaml
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](references/ci-workflow.md).

### 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](references/test-examples.md).

## 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:

```bash
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:

```bash
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](references/ci-workflow.md) and the complete unit +
integration suites in [references/test-examples.md](references/test-examples.md).

## Resources

- [GitHub Actions documentation](https://docs.github.com/en/actions)
- [GitHub encrypted secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets)
- [Full CI workflow reference](references/ci-workflow.md)
- [Test examples reference](references/test-examples.md)

## Next Steps

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