posthog-ci-integration

name	posthog-ci-integration
description	Configure PostHog CI/CD with GitHub Actions: unit tests with mocked PostHog, integration tests against a dev project, and deployment annotations. Trigger: "posthog CI", "posthog GitHub Actions", "posthog automated tests", "CI posthog", "posthog pipeline".
allowed-tools	Read, Write, Edit, Bash(gh:*)
version	1.12.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","posthog","testing","ci-cd"]
compatibility	Designed for Claude Code

PostHog CI Integration

Overview

Set up CI/CD pipelines for PostHog integrations. Covers mocked unit tests (no API key needed), integration tests against a PostHog dev project, and deployment annotations that mark releases in your PostHog timeline.

Prerequisites

• GitHub repository with Actions enabled
• PostHog dev project API key for integration tests
• PostHog personal API key for deployment annotations
• npm/pnpm project with vitest or jest

Instructions

Step 1: Configure GitHub Secrets

set -euo pipefail
# Project key for integration tests (phc_... from dev project)
gh secret set POSTHOG_TEST_KEY --body "phc_dev_project_key"

# Personal key for deployment annotations (phx_...)
gh secret set POSTHOG_PERSONAL_API_KEY --body "phx_your_personal_key"

# Project ID for annotations
gh secret set POSTHOG_PROJECT_ID --body "12345"

Step 2: GitHub Actions Workflow

# .github/workflows/posthog-tests.yml
name: PostHog 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 PostHog — no API key needed

  integration-tests:
    runs-on: ubuntu-latest
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    needs: unit-tests
    env:
      NEXT_PUBLIC_POSTHOG_KEY: ${{ secrets.POSTHOG_TEST_KEY 
       
    
        
        
        
           
           
         
          
         

  
     
           
     
    
          
        
             
             
         

Step 3: Unit Tests with Mocked PostHog

// tests/analytics.test.ts — runs in CI without any API keys
import { describe, it, expect, vi, beforeEach } from 'vitest';

vi.mock('posthog-node', () => ({
  PostHog: vi.fn().mockImplementation(() => ({
    capture: vi.fn(),
    identify: vi.fn(),
    getFeatureFlag: vi.fn().mockResolvedValue('control'),
    isFeatureEnabled: vi.fn().mockResolvedValue(true),
    getAllFlags: vi.fn().mockResolvedValue({ 'new-feature': true }),
    flush: vi.fn().mockResolvedValue(undefined),
    shutdown: vi.fn().mockResolvedValue(undefined),
  })),
}));

import { PostHog } from 'posthog-node';

describe('PostHog Analytics', () => {
  let ph: InstanceType<typeof PostHog>;

  beforeEach( {
    vi.();
    ph =  ();
  });

  (,  {
    ph.({
      : ,
      : ,
      : { : , :  },
    });

    (ph.).(
      expect.({
        : ,
        : expect.({ :  }),
      })
    );
  });

  (,  () => {
     enabled =  ph.(, );
    (enabled).();
  });

  (,  () => {
     variant =  ph.(, );
    (variant).();
  });
});

Step 4: Integration Tests (Real PostHog Project)

// tests/integration/posthog.test.ts
import { describe, it, expect, afterAll } from 'vitest';
import { PostHog } from 'posthog-node';

const KEY = process.env.NEXT_PUBLIC_POSTHOG_KEY;

describe.skipIf(!KEY)('PostHog Integration', () => {
  const ph = new PostHog(KEY!, {
    host: process.env.POSTHOG_HOST || 'https://us.i.posthog.com',
    flushAt: 1,
    flushInterval: 0,
  });

  afterAll(async () => await ph.shutdown());

  it('captures and flushes an event', async () => {
    ph.capture({
      distinctId: `ci-${Date.now()}`,
      event: 'ci_integration_test',
      properties: {
        ci: true,
        run_id: process.env.GITHUB_RUN_ID || 'local',
      },
    });
    await (ph.())...();
  });

  (,  () => {
     flags =  ph.();
    ( flags).();
  });

  (,  () => {
     response =  (, {
      : ,
      : { :  },
      : .({ : , :  }),
    });
    (response.).();
     data =  response.();
    (data).();
  });
});

Step 5: Package Scripts

{
  "scripts": {
    "test": "vitest run",
    "test:integration": "vitest run tests/integration/",
    "test:coverage": "vitest run --coverage"
  }
}

Error Handling

Issue	Cause	Solution
Integration tests fail in CI	Secret not configured	Run gh secret set POSTHOG_TEST_KEY
Tests timeout	PostHog unreachable from CI runner	Increase timeout, add retry
Annotation fails	Wrong personal key	Verify phx_ key, check project ID
Mock type mismatch	PostHog SDK updated	Update mock to match new SDK exports

Output

• Unit test suite with mocked PostHog (runs everywhere, no keys needed)
• Integration test suite against PostHog dev project (runs on main only)
• Deployment annotations marking each release in PostHog timeline
• GitHub Actions workflow with proper secret management

Resources

• GitHub Actions Secrets
• PostHog Annotations API
• Vitest Documentation

Next Steps

For deployment patterns, see posthog-deploy-integration.