Why multi-project flags are a distinct problem
Teams running separate PostHog projects per environment or per product surface (common for staging/production separation, or for multi-product companies) hit a specific failure mode: a flag created independently in each project drifts - different rollout percentages, different targeting rules, someone forgets to update one of them. Multi-project flag management exists to give a flag one canonical definition that propagates, rather than depending on manual discipline across every project.
Implementation done properly
| Piece | What it's for | What to get right |
|---|---|---|
| Multi-project flag definition | One flag, consistent rollout/targeting logic across the linked projects | Decide which projects actually should share a flag versus which need independent control - not every flag belongs in this category |
| Flags API | Programmatic flag evaluation and management outside the PostHog UI - CI/CD gating, server-side evaluation, custom tooling | API-evaluated flags need the same naming and ownership discipline as UI-managed ones, or the two drift apart |
| VS Code extension flag management | Checking or toggling flag state without leaving the editor, useful during active feature development | Convenient for individual developer workflow; not a substitute for a documented rollout process at the team level |
| Documented use cases | PostHog's own feature-flag use-case patterns (kill switches, gradual rollouts, permissioning) as a reference for what a flag is actually for before creating one | A flag created without a defined use case in mind is the first candidate for becoming permanent technical debt |
Exposure: confirming the flag is actually doing what you configured
Exposure tracking (recording which users actually evaluated a flag and which variant they received) is what lets you distinguish "the flag is configured for 20% rollout" from "20% of the relevant population has actually been exposed to it" - those are not automatically the same number if evaluation is gated behind another condition, or if a code path evaluates the flag inconsistently.
How to verify it worked
- Confirm the flag evaluates identically across all linked projects for a matching test user/context - a multi-project flag that returns different values per project defeats the purpose.
- For API-evaluated flags, check that a server-side evaluation and a client-side evaluation for the same user return the same variant, unless intentionally configured otherwise.
- Pull exposure data after rollout and compare it against the configured rollout percentage - a material gap usually means the flag is gated behind a condition (a feature check, an environment check) that is filtering who gets evaluated at all.
- Confirm flag changes made via the VS Code extension or API show up identically in the PostHog UI - a management surface that is out of sync with the source of truth is worse than not having it.