Copying Flags Across Projects

1---
2name: copying-flags-across-projects
3description: 'Copy a feature flag from one PostHog project to one or more target projects in the same organization. Use when the user wants to duplicate a flag, promote a flag from staging to production, sync flags across projects, or replicate a flag configuration in a different workspace. Covers cohort remapping, scheduled-change handling, encrypted payloads, and the safe defaults (disabled in target, no scheduled changes).'
4---
5 
6# Copying feature flags across projects
7 
8This skill guides you through duplicating a feature flag from a source project into one or more target projects within the same PostHog organization.
9 
10## When to use this skill
11 
12- The user asks to "copy a flag to another project", "duplicate this flag", or "sync a flag between projects"
13- The user wants to promote a flag from a staging project to a production project (or vice versa)
14- The user wants to replicate a flag configuration in a different workspace and keep cohort dependencies intact
15- The user is working around the absence of true environments by using projects-as-environments
16 
17## What this skill does not cover
18 
19- **Cross-organization copy** is not supported. The endpoint requires source and target projects to belong to the same org.
20- **Bulk copying every flag in a project**. The tool copies one flag at a time. For batch copies, loop through flag keys; each call is independent.
21- **Cleaning up old or stale flags** — see the `cleaning-up-stale-feature-flags` skill instead.
22 
23## Workflow
24 
25### 1. Resolve the source flag
26 
27You need the flag's **key** and the **source project's id**.
28 
29- If the user gave a flag key and a project id, use them directly.
30- If the user gave a flag name (e.g. "the new pricing flag"), call `posthog:feature-flag-get-all` in the source project to find the matching flag and read its `key`.
31- If the user only gave a flag and not a project, ask which project it lives in. Don't assume the active MCP project — copying out of the wrong source is a common foot-gun.
32 
33### 2. Resolve target project ids
34 
35Targets must be in the same organization as the source. Call `posthog:projects-get` to list available projects and confirm membership before issuing the copy.
36 
37For a multi-target copy, the tool accepts up to 50 target project ids in a single call. Successes and failures are reported per target, so a partial failure does not block the rest.
38 
39### 3. Preview the source flag
40 
41Call `posthog:feature-flag-get-definition` on the source flag and present a concise summary to the user before copying:
42 
43- Flag key, name, and active state in the source
44- Filter groups (rollout %, property filters, variant splits)
45- Any cohort references in `filters.groups[].properties[]` — these will be remapped server-side, but the user should know whether the target project already has matching cohorts
46- Whether the flag has encrypted payloads (`has_encrypted_payloads`) or is remote configuration (`is_remote_configuration`)
47- Whether scheduled changes exist (the user can opt to copy them in step 4)
48 
49### 4. Confirm copy options
50 
51Default to the safest combination and ask the user to override only if they explicitly want different behavior:
52 
53- **`disable_copied_flag: true`** — the copied flag lands disabled in the target. Recommended by default; turning a flag on in a new project should be a deliberate, observed action.
54- **`copy_schedule: false`** — scheduled changes do not come along. Recommended by default; schedules are usually project-specific.
55 
56If the user says "promote it as-is" or "turn it on in prod", switch `disable_copied_flag` to `false`. If they say "include the rollout schedule" or "with the scheduled rollout", switch `copy_schedule` to `true`.
57 
58### 5. Execute the copy
59 
60Call `posthog:feature-flags-copy-flags-create` with:
61 
62- `feature_flag_key`: the source flag's key
63- `from_project`: the source project id
64- `target_project_ids`: the resolved list of target project ids
65- `disable_copied_flag`: from step 4 (default `true`)
66- `copy_schedule`: from step 4 (default `false`)
67 
68### 6. Report per-target outcome
69 
70The response includes a `success` array (one entry per copied flag) and a `failed` array (per-target errors). Surface both:
71 
72- For each success: target project id, the new flag's id, and its `active` state in the target.
73- For each failure: target project id and the error message. Common causes are missing editor access on the target team, or the flag already existing as a non-overridable resource in the target.
74 
75If any targets failed, ask the user whether to retry the failed ones, skip them, or fix the underlying issue (e.g. grant access, then retry).
76 
77## Important notes
78 
79- **Cohorts are remapped automatically.** When the source flag references a cohort, the endpoint creates or reuses an equivalent cohort in each target project and rewrites the flag's filters to point at the target-project cohort id. You don't need to handle this — but tell the user it's happening so they understand the new cohorts that may appear in the target.
80- **Encrypted payloads are preserved.** Remote-configuration flags with encrypted payloads keep their encryption when copied; the payload is re-encrypted under the target project's key.
81- **Scheduled changes copy with cohort remap too.** If `copy_schedule: true`, any scheduled cohort references are remapped just like the live filter conditions.
82- **Auth requirements.** The user's API key must include explicit `feature_flag:write` (or `feature_flag:*`) scope. A `*`-only key will be rejected — this endpoint is gated by an INTERNAL viewset and `*` consent does not satisfy it. Team-scoped keys cannot reach this endpoint either; an org-scoped or unscoped key is required.
83- **Editor access on the source.** The user must have at least editor-level access on the source flag's team. The endpoint enforces this via PostHog's access control before copying.
84- **Per-target access on targets.** Targets the user can't see are silently dropped from the result; targets they can see but lack edit rights on appear in the `failed` array with a permission error.
85- **No undo.** A copy creates a new flag in the target (or overwrites an existing flag with the same key). Always confirm with the user before issuing the copy, especially when the target is a production project.
86 
87## Example interaction
88 
89> **User:** Copy the `new-checkout` flag from project 12345 to project 67890.
90>
91> **Agent:** Looking at the source flag in project 12345.
92>
93> _(calls `posthog:feature-flag-get-definition`)_
94>
95> The `new-checkout` flag is currently a boolean at 25% rollout in project 12345, with no cohort filters and no scheduled changes. I'll copy it as **disabled** in project 67890 with no scheduled changes — this is the safer default. Confirm?
96>
97> **User:** Yes, but enable it in the target.
98>
99> **Agent:** Got it — enabling in the target.
100>
101> _(calls `posthog:feature-flags-copy-flags-create` with `disable_copied_flag: false`, `copy_schedule: false`)_
102>
103> Done. Created flag id 99887 in project 67890 (`active: true`). No failed targets.
104 
105## Available tools
106 
107- `posthog:feature-flags-copy-flags-create` — performs the copy. Required fields: `feature_flag_key`, `from_project`, `target_project_ids`. Optional: `disable_copied_flag`, `copy_schedule`.
108- `posthog:feature-flag-get-all` — find a flag by key/name in a given project when the user only gave a friendly name.
109- `posthog:feature-flag-get-definition` — fetch the full source flag (filters, variants, cohort references, encryption flags) so you can preview before copying.
110- `posthog:projects-get` — list projects in the active organization, used to resolve and validate target project ids.
111