Pulumi PostHog Provider

A Pulumi provider for managing PostHog analytics, product insights, and feature flag resources, dynamically bridged from the Terraform PostHog Provider.

Introduction

This package provides a Pulumi provider that enables you to manage your PostHog product analytics and feature flag infrastructure using TypeScript, JavaScript, Python, Go, or C#. The provider is automatically generated from the Terraform PostHog provider, giving you access to all its functionality within the Pulumi ecosystem.

Features

• Product Analytics: Configure projects and insights for analyzing user behavior
• Feature Flags: Create and manage feature flags with rollout strategies and targeting rules
• Event Actions: Define custom actions to track specific user behaviors
• Dashboards: Build and maintain custom dashboards with custom layouts for data visualization
• Alerts: Monitor metrics and get notified when thresholds are exceeded
• Hog Functions: Run custom server-side transformations and destinations
• Surveys: Create project-scoped surveys with targeting and iteration scheduling
• External Data Sources: Sync data from external systems (Postgres, Stripe, etc.) into PostHog
• Proxy Records: Provision custom-domain proxy records at the organization level
• Access Control: Manage organizations, roles, role memberships, and project-level access
• TypeScript Support: Full type safety with comprehensive TypeScript definitions

Installation

npm

npm install pulumi-posthog

yarn

yarn add pulumi-posthog

pnpm

pnpm add pulumi-posthog

bun

bun add pulumi-posthog

Configuration

Before using the PostHog provider, you need to configure your API credentials.

Required Configuration

• API Key: Your PostHog Personal API Key
• Host: Your PostHog instance URL (e.g., https://app.posthog.com or your self-hosted URL)

Environment Variables

export POSTHOG_API_KEY="your-api-key-here"
export POSTHOG_HOST="https://app.posthog.com"

Pulumi Configuration

import * as pulumi from '@pulumi/pulumi'

const config = new pulumi.Config('posthog')
config.require('apiKey')
config.require('host')

Or using the Pulumi CLI:

pulumi config set posthog:apiKey "your-api-key-here" --secret
pulumi config set posthog:host "https://app.posthog.com"

Quick Start

Feature Flag Example

import * as pulumi from '@pulumi/pulumi'
import * as posthog from 'pulumi-posthog'

// Create a feature flag (filters is a JSON-encoded string)
const betaFeature = new posthog.FeatureFlag('beta-feature', {
  key: 'new-dashboard',
  name: 'New Dashboard Beta',
  active: true,
  filters: JSON.stringify({
    groups: [
      {
        properties: [],
        rolloutPercentage: 25,
      },
    ],
  }),
})

// Export the feature flag key
export const featureFlagKey = betaFeature.key

Project Example

import * as pulumi from '@pulumi/pulumi'
import * as posthog from 'pulumi-posthog'

// Create a new project
const project = new posthog.Project('analytics-project', {
  name: 'Production Analytics',
  timezone: 'UTC',
})

// Export the project ID
export const projectId = project.id

Action Example

import * as pulumi from '@pulumi/pulumi'
import * as posthog from 'pulumi-posthog'

// Create a custom action to track button clicks (steps is a JSON-encoded string)
const buttonClickAction = new posthog.Action('button-click', {
  name: 'Checkout Button Click',
  description: 'Tracks when users click the checkout button',
  stepsJson: JSON.stringify([
    {
      event: '$autocapture',
      selector: '#checkout-button',
      url: '/cart',
    },
  ]),
})

// Export the action ID
export const actionId = buttonClickAction.id

Available Resources

This provider supports the following PostHog resources:

• Project: Manage PostHog projects
• FeatureFlag: Create and configure feature flags with targeting rules
• Action: Define custom event actions
• Dashboard / DashboardLayout: Build custom dashboards and place insights on them
• Insight: Configure analytics insights (trends, funnels, retention, etc.)
• Alert: Set up alerts on insights with absolute or relative thresholds
• HogFunction: Run custom Hog code for transformations and destinations
• Survey: Create and manage project-scoped user surveys
• ExternalDataSource: Sync data from external systems (Postgres, Stripe, etc.)
• ProxyRecord: Provision PostHog reverse-proxy records on custom domains
• AccessControl / OrganizationMember / ProjectMember / ProjectDefaultAccess / Role / RoleMembership: Manage access and permissions

Advanced Usage

Feature Flag with Complex Targeting

import * as posthog from 'pulumi-posthog'

const advancedFlag = new posthog.FeatureFlag('advanced-targeting', {
  key: 'premium-features',
  name: 'Premium Features',
  active: true,
  filters: JSON.stringify({
    groups: [
      {
        properties: [
          {
            key: 'plan',
            value: 'premium',
            type: 'person',
            operator: 'exact',
          },
        ],
        rolloutPercentage: 100,
      },
      {
        properties: [],
        rolloutPercentage: 10, // 10% rollout for non-premium users
      },
    ],
  }),
})

Project-Scoped Survey

import * as posthog from 'pulumi-posthog'

const npsSurvey = new posthog.Survey('nps-survey', {
  name: 'NPS Q2',
  type: 'popover',
  projectId: '12345',
  questionsJson: JSON.stringify([
    {
      type: 'rating',
      question: 'How likely are you to recommend us?',
      scale: 10,
    },
  ]),
})

External Data Source

import * as posthog from 'pulumi-posthog'

const stripeSource = new posthog.ExternalDataSource('stripe', {
  sourceType: 'Stripe',
  projectId: '12345',
  schemas: ['Customer', 'Invoice', 'Subscription'],
  syncFrequency: 'day',
  // Secrets are redacted by PostHog when read; values stay in Pulumi state.
  jobInputsJson: JSON.stringify({
    stripe_account_id: 'acct_123',
    stripe_secret_key: 'sk_live_...',
  }),
})

Custom-Domain Proxy Record

import * as posthog from 'pulumi-posthog'

// Provision a reverse proxy on a custom domain. After apply, point a CNAME
// record at `proxy.targetCname` to complete provisioning.
const proxy = new posthog.ProxyRecord('marketing-proxy', {
  domain: 'analytics.example.com',
})

export const cnameTarget = proxy.targetCname

Authentication

Getting Your API Key

1. Log in to your PostHog instance
2. Navigate to Settings → User → Personal API Keys
3. Click Create Personal API Key
4. Copy the generated key
5. Set it as an environment variable or Pulumi config:

# Environment variable
export POSTHOG_API_KEY="phx_your_api_key_here"

# Or Pulumi config (recommended)
pulumi config set posthog:apiKey "phx_your_api_key_here" --secret

Self-Hosted PostHog

If you're using a self-hosted PostHog instance, configure the host:

export POSTHOG_HOST="https://posthog.yourcompany.com"
# or
pulumi config set posthog:host "https://posthog.yourcompany.com"

Documentation

For detailed documentation on all available resources and their properties, visit:

• PostHog Documentation
• Terraform PostHog Provider
• Pulumi Documentation

Troubleshooting

Authentication Errors

If you encounter authentication errors:

1. Verify your API key is correct and not expired
2. Ensure your API key has the necessary permissions
3. Check that your host URL is correctly configured
4. Confirm network connectivity to your PostHog instance

Resource Not Found

If resources aren't found after creation:

1. Check that you're using the correct project ID
2. Verify the resource was created successfully in the PostHog UI
3. Ensure your API key has access to the project

Common Issues

Issue: 401 Unauthorized error
Solution: Verify your API key is valid and properly configured

Issue: 403 Forbidden error
Solution: Check that your API key has the required permissions for the operation

Issue: Resources not appearing in PostHog UI
Solution: Wait a few moments for replication, or check if you're viewing the correct project

Examples

For more examples, check out the examples directory in the repository.

Contributing

Contributions are welcome! Please read the Contributing Guide for details on our code of conduct and the process for submitting pull requests.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• PostHog Community: PostHog Slack

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• PostHog for building an amazing product analytics platform
• Terraform PostHog Provider maintainers
• Pulumi for the infrastructure as code platform
• The open-source community for continuous support and contributions

Related Projects

• PostHog - Open-source product analytics
• Pulumi Terraform Bridge - Bridge technology
• Other Pulumi Providers - More bridged providers

Part of the Pulumi Any Terraform collection