copying-flags-across-projects

Files (1)

• SKILL.md

SKILL.md (first lines)

# Copying feature flags across projects

This skill guides you through duplicating a feature flag from a source project into one or more target projects within the same PostHog organization.

## When to use this skill

- The user asks to "copy a flag to another project", "duplicate this flag", or "sync a flag between projects"
- The user wants to promote a flag from a staging project to a production project (or vice versa)
- The user wants to replicate a flag configuration in a different workspace and keep cohort dependencies intact
- The user is working around the absence of true environments by using projects-as-environments

## What this skill does not cover

- **Cross-organization copy** is not supported. The endpoint requires source and target projects to belong to the same org.
- **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.
- **Cleaning up old or stale flags** — see the `cleaning-up-stale-feature-flags` skill instead.

## Workflow

### 1. Resolve the source flag

You need the flag's **key** and the **source project's id**.

- If the user gave a flag key and a project id, use them directly.
- 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`.
- 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.

### 2. Resolve target project ids

Targets must be in the same organization as the source. Call `posthog:projects-get` to list available projects and confirm membership before issuing the copy.

For 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.

### 3. Preview the source flag and its dependencies

Call `posthog:feature-flag-get-definition` on the source flag. Then always call `posthog:feature-flags-copy-dependencies-check` with `feature_flag_key`, `from_project`, and `target_project_ids`, rather than trying to detect dependencies first — it copies nothing, and returns an empty result with no warnings when the flag has none, so running it on every copy is cheap and never skips a real dependency.

A false `can_copy_dependencies` does not always mean the copy is blocked. It is also false when there is nothing to copy. Report a problem only when `warnings` is non-empty.

Present a concise summary to the user before copying:

- Flag key, name, and active state in the source
- Filter groups (rollout %, property filters, variant splits)
- 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
- Whether the flag has encrypted payloads (`has_encrypted_payloads`) or is remote configuration (`is_remote_configuration`)
- Whether scheduled changes exist (the user can opt to copy them in step 4)
- The dependency check's `copied_dependency_keys` (dependencies a copy would create in a target), `reused_dependency_keys` (dependencies a target already satisfies), and any `warnings`

### 4. Confirm copy options

One confirmation covers all three options. Default to the safest combination and ask the user to override only if they explicitly want different behavior:

- **`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.
- **`copy_schedule: false`** — scheduled changes do not come along. Recommended by default; schedules are usually project-specific.
- **`copy_dependencies: false`** — dependency flags do not come along. Set it to `true` only when the user approves copying the keys step 3's check reported.

If 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`.

### 5. Execute the copy

Call `posthog:feature-flags-copy-flags-create` with:

- `feature_flag_key`: the source flag's key
- `from_project`: the source project id
- `target_project_ids`: the resolved list of target project ids
- `disable_copied_flag`: from step 4 (default `true`)
- `copy_schedule`: from step 4 (default `false`)
- `copy_dependencies`: from step 4 (default `false`). Omitting it silently skips dependency copying, even when the user approved it.

### 6. Report per-target outcome

The response includes a `success` array (one entry per copied flag) and a `failed` array (per-target errors). Surface both:

- For each success: target project id, the new flag's id, and its `active` state in the target.
- 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.

If 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).

## Important notes

- **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.
- **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.
- **Scheduled changes copy with cohort remap too.** If `copy_schedule: true`, any scheduled cohort references are remapped just like the live filter conditions.
- **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.
- **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.
- **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.
- **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.

## Example interaction

> **User:** Copy the `new-checkout` flag from project 12345 to project 67890.
>
> **Agent:** Looking at the source flag in project 12345.
>
> _(calls `posthog:feature-flag-get-definition`)_
>
> 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?
>
> **User:** Yes, but enable it in the target.
>
> **Agent:** Got it — enabling in the target.
>
> _(calls `posthog:feature-flags-copy-flags-create` with `disable_copied_flag: false`, `copy_schedule: false`)_
>
> Done. Created flag id 99887 in project 67890 (`active: true`). No failed targets.

## Available tools

- `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`, `copy_dependencies`.
- `posthog:feature-flags-copy-dependencies-check` — previews what a copy would do to the flag's transitive flag dependencies. Copies nothing. Call it before every copy; it returns an empty result when the flag has no dependencies.
- `posthog:feature-flag-get-all` — find a flag by key/name in a given project when the user only gave a friendly name.
- `posthog:feature-flag-get-definition` — fetch the full source flag (filters, variants, cohort references, encryption flags) so you can preview before copying.
- `posthog:projects-get` — list projects in the active organization, used to resolve and validate target project ids.

From PostHog/skills, MIT.