copying-flags-across-projects

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Copying feature flags across projects

跨项目复制feature flag

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

此技能将引导你在同一PostHog组织内，把一个feature flag从源项目复制到一个或多个目标项目中。

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

用户要求“将flag复制到另一个项目”、“复制此flag”或“跨项目同步flag”
用户想要将flag从staging项目推广到生产项目（反之亦然）
用户想要在不同工作区中复制flag配置，并保持群组依赖关系完整
用户通过“以项目为环境”的方式，来替代缺失的真实环境功能

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.

跨组织复制：不支持该操作。接口要求源项目和目标项目必须属于同一组织。
批量复制项目中的所有flag：本工具一次只能复制一个flag。如需批量复制，需遍历flag键；每次调用均独立执行。
清理旧的或过期的flag —— 请使用
```
cleaning-up-stale-feature-flags
```
技能。

Workflow

工作流程

1. Resolve the source flag

1. 确定源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.

你需要flag的键（key）和源项目ID。

如果用户提供了flag键和项目ID，直接使用即可。
如果用户提供了flag名称（例如“新定价flag”），在源项目中调用
```
posthog:feature-flag-get-all
```
来查找匹配的flag并读取其
```
key
```
。
如果用户仅提供了flag但未指定项目，请询问该flag所在的项目。不要默认使用当前活跃的MCP项目 —— 从错误的源项目复制是常见的失误。

2. Resolve target project ids

2. 确定目标项目ID

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.

目标项目必须与源项目属于同一组织。调用

posthog:projects-get

列出可用项目，并在执行复制前确认成员资格。

对于多目标复制，工具单次调用最多接受50个目标项目ID。结果会按每个目标项目分别报告成功或失败，因此部分失败不会阻碍其他项目的复制。

3. Preview the source flag

3. 预览源flag

Call

posthog:feature-flag-get-definition

on the source flag and 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)

调用

posthog:feature-flag-get-definition

获取源flag的信息，并在复制前向用户展示简洁的摘要：

源项目中的flag键、名称和激活状态
筛选组（发布百分比、属性筛选、变体拆分）
```
filters.groups[].properties[]
```
中的任何cohort引用 —— 这些会在服务器端自动重映射，但用户应了解目标项目是否已有匹配的cohort
flag是否包含加密负载（
```
has_encrypted_payloads
```
）或为远程配置（
```
is_remote_configuration
```
）
是否存在计划变更（用户可在步骤4中选择是否复制这些变更）

4. Confirm copy options

4. 确认复制选项

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.

If the user says "promote it as-is" or "turn it on in prod", switch

disable_copied_flag

false

. If they say "include the rollout schedule" or "with the scheduled rollout", switch

copy_schedule

true

默认采用最安全的组合，仅当用户明确要求不同行为时才进行修改：

disable_copied_flag: true
—— 复制后的flag在目标项目中处于禁用状态。默认推荐此设置；在新项目中启用flag应是一个经过深思熟虑、可观测的操作。
copy_schedule: false
—— 不复制计划变更。默认推荐此设置；计划通常是项目特定的。

如果用户说“按原样推广”或“在生产环境中启用”，则将

disable_copied_flag

设为

false

。如果用户说“包含发布计划”或“连同计划发布一起复制”，则将

copy_schedule

设为

true

。

5. Execute the copy

5. 执行复制

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
```
)

调用

posthog:feature-flags-copy-flags-create

，参数包括：

```
feature_flag_key
```
：源flag的键
```
from_project
```
：源项目ID
```
target_project_ids
```
：已确定的目标项目ID列表
```
disable_copied_flag
```
：步骤4中的设置（默认
```
true
```
）
```
copy_schedule
```
：步骤4中的设置（默认
```
false
```
）

6. Report per-target outcome

6. 报告每个目标项目的结果

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

响应包含

success

数组（每个复制成功的flag对应一条记录）和

failed

数组（每个目标项目的错误信息）。需同时展示这两部分：

对于每个成功项：目标项目ID、新flag的ID及其在目标项目中的
```
active
```
状态。
对于每个失败项：目标项目ID和错误信息。常见原因包括目标团队缺少编辑权限，或目标项目中已存在无法覆盖的同名flag资源。

如果有任何目标项目复制失败，请询问用户是否要重试失败项、跳过它们，或修复潜在问题（例如授予权限后重试）。

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.

Cohort会自动重映射：当源flag引用某个cohort时，接口会在每个目标项目中创建或复用等效的cohort，并重新编写flag的筛选条件以指向目标项目的cohort ID。你无需手动处理此操作，但需告知用户这一情况，以便他们了解目标项目中可能出现的新cohort。
加密负载会被保留：带有加密负载的远程配置flag在复制后仍会保持加密状态；负载会使用目标项目的密钥重新加密。
计划变更复制时也会进行cohort重映射：如果
```
copy_schedule: true
```
，任何计划中的cohort引用会像实时筛选条件一样被重映射。
权限要求：用户的API密钥必须包含明确的
```
feature_flag:write
```
（或
```
feature_flag:*
```
）权限范围。仅含
```
*
```
的密钥会被拒绝 —— 此接口由INTERNAL视图集管控，
```
*
```
权限无法满足要求。团队范围的密钥也无法访问此接口；需要组织范围或无范围限制的密钥。
源项目的编辑权限：用户必须至少拥有源flag所在团队的编辑级权限。接口会在复制前通过PostHog的访问控制机制强制执行此要求。
目标项目的逐项目权限：用户无法查看的目标项目会被从结果中自动剔除；用户可见但缺少编辑权限的目标项目会出现在
```
failed
```
数组中，并显示权限错误。
无法撤销：复制操作会在目标项目中创建新flag（或覆盖同名的现有flag）。在执行复制前务必与用户确认，尤其是当目标项目为生产环境时。

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.

用户： 将
new-checkout
flag从项目12345复制到项目67890。
Agent： 正在查看项目12345中的源flag。
(调用
posthog:feature-flag-get-definition
)
new-checkout
flag目前在项目12345中是一个25%发布比例的布尔型flag，无cohort筛选条件，也无计划变更。我将按禁用状态把它复制到项目67890，且不复制计划变更 —— 这是更安全的默认设置。是否确认？
用户： 确认，但要在目标项目中启用它。

Agent： 收到 —— 将在目标项目中启用。
(调用
posthog:feature-flags-copy-flags-create
，参数
disable_copied_flag: false
,
copy_schedule: false
)
完成。已在项目67890中创建flag ID 99887（
active: true
）。无失败的目标项目。

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

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

posthog:feature-flags-copy-flags-create

—— 执行复制操作。必填字段：

feature_flag_key

from_project

target_project_ids

。可选字段：

disable_copied_flag

copy_schedule

。

```
posthog:feature-flag-get-all
```
—— 当用户仅提供友好名称时，在指定项目中通过键/名称查找flag。
```
posthog:feature-flag-get-definition
```
—— 获取源flag的完整信息（筛选条件、变体、cohort引用、加密标志），以便在复制前预览。
```
posthog:projects-get
```
—— 列出当前活跃组织中的项目，用于确定和验证目标项目ID。