https://github.com/ashwamegh/growthbook2posthog
Migrate feature flags from GrowthBook to PostHog with an interactive CLI wizard.
https://github.com/ashwamegh/growthbook2posthog
feature-flags growthbook posthog
Last synced: 3 days ago
JSON representation
Migrate feature flags from GrowthBook to PostHog with an interactive CLI wizard.
- Host: GitHub
- URL: https://github.com/ashwamegh/growthbook2posthog
- Owner: ashwamegh
- License: mit
- Created: 2026-03-22T10:23:10.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-22T10:40:24.000Z (3 months ago)
- Last Synced: 2026-05-01T14:36:47.231Z (about 1 month ago)
- Topics: feature-flags, growthbook, posthog
- Language: TypeScript
- Homepage:
- Size: 64.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# growthbook2posthog
Migrate feature flags from [GrowthBook](https://www.growthbook.io/) to [PostHog](https://posthog.com/) with an interactive CLI wizard.
[](https://www.npmjs.com/package/growthbook2posthog)
[](https://github.com/ashwamegh/growthbook2posthog/blob/main/LICENSE)
## Why?
Switching feature flag providers shouldn't mean manually recreating hundreds of flags. `growthbook2posthog` reads your GrowthBook features, maps them to PostHog's flag format, and creates them in PostHog - handling all the edge cases along the way.
## Features
- **Interactive TUI** - Step-by-step wizard guides you through the entire migration
- **Works everywhere** - GrowthBook Cloud, PostHog Cloud (US/EU), and self-hosted instances
- **Smart key handling** - Automatically detects and replaces invalid characters (GrowthBook allows dots, PostHog doesn't) with your choice of separator
- **Environment-aware** - Optionally append environment names to flag keys for per-environment separation in PostHog
- **Safe by default** - Preview migration plan before executing, skip existing flags, per-flag error isolation
- **Incremental** - Re-run migrations safely; existing flags are detected and can be skipped or updated
- **Complete mapping** - Translates targeting conditions, rollout percentages, force rules, experiments, variants, and payloads
## Quick Start
```bash
# Install globally
npm install -g growthbook2posthog
# Run the wizard
gb2ph
```
Or run without installing:
```bash
npx growthbook2posthog
```
## How It Works
The wizard walks you through 7 steps:
```
Step 1 Configure GrowthBook Connect to Cloud or self-hosted instance
Step 2 Configure PostHog Connect to US/EU Cloud or self-hosted instance
Step 3 Select Source Pick GrowthBook project(s) and environment(s)
Step 4 Select Destination Pick PostHog project, map environments, choose key format
Step 5 Preview Migration Review the plan before making any changes
Step 6 Execute Migration Migrate flags with live progress
Step 7 Summary Report See results - created, skipped, failed
```
## What Gets Migrated
| GrowthBook | PostHog | Notes |
|------------|---------|-------|
| Feature key | Flag key | Invalid characters replaced with `_` or `-` |
| Description | Flag name | Direct mapping |
| Boolean features | Boolean flags | Direct mapping |
| String/JSON features | Multivariate flags | Mapped to variants with payloads |
| Force rules | Groups (100% rollout) | Conditions translated to property filters |
| Rollout rules | Groups (% rollout) | Percentage preserved |
| Experiment rules | Multivariate variants | Weights and payloads preserved |
| Tags | Tags | Direct mapping |
| Archived status | Active: false | Archived flags can be optionally skipped |
| Disabled environments | Active: false, 0% rollout | Flag exists but doesn't serve |
### Targeting Conditions
MongoDB-style conditions are translated to PostHog property filters:
| GrowthBook | PostHog |
|------------|---------|
| `$eq` | `exact` |
| `$ne` | `is_not` |
| `$in` / `$nin` | `exact` (array) / `is_not` (array) |
| `$regex` | `regex` |
| `$gt` / `$gte` / `$lt` / `$lte` | `gt` / `gte` / `lt` / `lte` |
| `$exists` | `is_set` / `is_not_set` |
| `$and` | Single group (AND) |
| `$or` | Multiple groups (OR) |
## Environment Strategies
GrowthBook has built-in environments. PostHog does not. The tool supports two approaches:
### Option A: Environment-Suffixed Keys
Append the environment name to each flag key. Best for single-project setups (including self-hosted free tier).
```
my_feature --> my_feature_production
my_feature --> my_feature_development
my_feature --> my_feature_sandbox
```
Run the migration once per environment. The wizard asks if you want to append environments.
### Option B: Separate PostHog Projects
Migrate each environment into a separate PostHog project. Cleanest separation, but requires PostHog Cloud or a paid plan (self-hosted free tier is limited to 1 project).
## Key Formatting
PostHog only allows **letters, numbers, hyphens (`-`) and underscores (`_`)** in flag keys.
If your GrowthBook keys use dots or other characters, the wizard detects this and lets you pick a separator:
```
ais.v1.account.get --> ais_v1_account_get (underscore)
ais.v1.account.get --> ais-v1-account-get (hyphen)
```
Keys that are already valid pass through unchanged.
## Configuration
Connection settings are saved locally after first use. On subsequent runs, the wizard offers to reuse them:
```
Use saved GrowthBook config? (http://localhost:3100) Yes
Use saved PostHog config? (https://us.posthog.com) Yes
```
Config is stored via [conf](https://github.com/sindresorhus/conf) in your OS config directory.
## API Keys
### GrowthBook
Go to **Settings > API Keys** and create a Secret API Key with read access to features, projects, and environments.
### PostHog
Go to **Settings > Personal API Keys** and create a key with scopes:
- **Feature Flags**: Read + Write
- **Projects**: Read
- **Organizations**: Read (+ Write if you want to create projects)
## Requirements
- Node.js >= 18
- GrowthBook API access (Secret API Key)
- PostHog API access (Personal API Key)
## Known Limitations
- **Experiment-ref** and **safe-rollout** rules in GrowthBook have no PostHog equivalent. These are flagged as warnings during migration.
- PostHog's self-hosted free tier is limited to **1 project**. Use environment-suffixed keys or upgrade for multi-project support.
- Complex nested MongoDB conditions may need manual review post-migration.
## Development
```bash
# Clone and install
git clone https://github.com/ashwamegh/growthbook2posthog.git
cd growthbook2posthog
npm install
# Build
npm run build
# Run locally
node dist/bin/gb2ph.js
# Watch mode
npm run dev
```
## License
MIT