sync-schema

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sync a Prepr schema with Git

使用 Git 同步 Prepr Schema

Set up and run Git-backed schema sync between a repository and Prepr environments. A schema change alters the structure of a live environment and can delete fields and their content, so the goal is a change that is reviewed before it lands and can be reverted. That is what Git sync gives you and the alternatives do not.

Read schema-route.md first: it explains how the files and the environment stay in step and what Export and Import do.

The user runs Export and Import in Prepr. Your part is valid files, an accurate impact assessment, and telling the user exactly what will happen. If Prepr MCP tools are connected (run the check), use them read-only to inspect the live schema of the source and target environment. Without them, work from the files and ask the user to confirm the target's current state.

在代码仓库与 Prepr 环境之间设置并运行基于 Git 的 Schema 同步。Schema 变更会改变线上环境的结构，并可能删除字段及其内容，因此目标是让变更在落地前经过审查，并且能够回滚。这正是 Git 同步能够提供、而其他方式无法提供的能力。

请先阅读 schema-route.md：其中说明了文件与环境如何保持一致，以及 Export 和 Import 的具体作用。

用户需要在 Prepr 中运行 Export 和 Import。 你的职责是确保文件有效、准确评估影响，并向用户明确说明将会发生什么。如果已连接 Prepr MCP 工具（运行检查），请以只读方式使用这些工具检查源环境和目标环境的线上 Schema。如果没有，则根据文件开展工作，并请用户确认目标环境的当前状态。

Ground rules

基本规则

Read the docs before acting:
- Syncing a schema: https://docs.prepr.io/development/working-with-cicd/syncing-a-schema
- Validating a schema: https://docs.prepr.io/development/working-with-cicd/validating-a-schema
- Exporting and importing: https://docs.prepr.io/development/working-with-cicd/exporting-and-importing-a-schema
- Environments: https://docs.prepr.io/project-setup/setting-up-environments
Export before editing, even for a one-line change. Ask the user to run Export (or pull the branch Prepr exports to) so you start from the current state. Editing a stale copy means hand-merging generated JSON later.
Validate before every import. See Validate.
Name the environment and its role (development, acceptance, production) every time you talk about an import.

行动前先阅读文档：
- 同步 Schema：https://docs.prepr.io/development/working-with-cicd/syncing-a-schema
- 验证 Schema：https://docs.prepr.io/development/working-with-cicd/validating-a-schema
- 导出与导入：https://docs.prepr.io/development/working-with-cicd/exporting-and-importing-a-schema
- 环境：https://docs.prepr.io/project-setup/setting-up-environments
即使只改一行，也要在编辑前先 Export。 请用户运行 Export（或拉取 Prepr 导出到的分支），这样你才能从当前状态开始。编辑过时的副本意味着稍后必须手动合并生成的 JSON。
每次 import 前都要验证。 参见验证。
每次谈及 import 时，都要说明环境及其角色（开发、验收、生产）。

A commit is not a sync

提交并不等于同步

Committing and pushing changes under

prepr/schema/

changes no Prepr environment. The schema only changes when someone runs Import in Prepr. This is the most expensive misunderstanding in this area.

Never report a schema change as live because it was pushed or merged.
Hold back front-end code that queries a new model or field until the import is confirmed: keep the query fragment out, or keep the type shim.
Say who runs the import, in which environment and when. Keep schema commits separate from feature commits so they can be coordinated.

仅在

prepr/schema/

下提交并推送变更不会改变任何 Prepr 环境。只有有人在 Prepr 中运行 Import，Schema 才会发生变化。这是该领域代价最高的误解。

不要因为 Schema 变更已推送或合并，就将其报告为已上线。
在确认 import 完成之前，暂缓发布查询新 Model 或字段的前端代码：先移除查询片段，或保留 type shim。
明确说明由谁、在哪个环境、于何时运行 import。将 Schema commit 与功能 commit 分开，以便协调。

Git sync is the recommendation

Setting up Git sync

设置 Git 同步

The connection is configured in Prepr, per environment or organization, following the syncing guide for the user's provider. The token needs write access to the repository's contents. The Sync schema action needs a Developer or Admin role with Schema write permission in that environment.

The repository side is yours:

One directory,
prepr/schema/
, with one JSON file per entity, in the format of schema-files.md. Keep it out of any build or bundling path.

CI validation on every pull request that touches it, with the official workflow. Save it as

.github/workflows/prepr-schema-validation.yml

yaml

name: Validate Prepr schema

on:
  workflow_dispatch:
  pull_request:
    paths:
      - 'prepr/schema/*.json'
  push:
    branches:
      - main
    paths:
      - 'prepr/schema/*.json'

jobs:
  validate-prepr-schema:
    uses: preprio/action-schema-validation/.github/workflows/prepr-schema-validation.yml@v1.0.15

Check https://github.com/preprio/action-schema-validation for a newer tag before you pin it.

Schema changes in their own commits, separate from feature code.
The direction agreed up front: which environment exports to the repository and which environments import from it (Export only, Import only, or both). Write it in the project's README or agent instructions; newcomers get it wrong.

连接需按照用户提供平台的同步指南，在 Prepr 中按环境或组织进行配置。访问令牌需要对仓库内容具有写入权限。Sync schema 操作要求用户在该环境中拥有 Developer 或 Admin 角色，以及 Schema 写入权限。

仓库端由你负责配置：

**使用一个目录
```
prepr/schema/
```
，**每个 Entity 对应一个 JSON 文件，格式参见 schema-files.md。确保该目录不进入任何构建或打包路径。

对每个修改该目录的 pull request 执行 CI 验证，并使用官方 workflow。将其保存为

.github/workflows/prepr-schema-validation.yml

：

yaml

name: Validate Prepr schema

on:
  workflow_dispatch:
  pull_request:
    paths:
      - 'prepr/schema/*.json'
  push:
    branches:
      - main
    paths:
      - 'prepr/schema/*.json'

jobs:
  validate-prepr-schema:
    uses: preprio/action-schema-validation/.github/workflows/prepr-schema-validation.yml@v1.0.15

固定版本前，请检查 https://github.com/preprio/action-schema-validation 是否有更新的 tag。

**Schema 变更使用独立的 commit，**与功能代码分开。
**提前约定同步方向：**哪个环境 export 到仓库，哪些环境从仓库 import（仅 Export、仅 Import，或两者兼有）。将其写入项目的 README 或 Agent 指令；新成员经常弄错。

Editing schema files

编辑 Schema 文件

Follow schema-files.md for keys, field types and file names, and schema-design-principles.md for design. A file name that does not match its entity's name stops Prepr from mapping files to entities. Keep every

ref

stable; cross-references between files use it.

有关 key、字段类型和文件名的规则，请遵循 schema-files.md；设计原则请遵循 schema-design-principles.md。文件名与 Entity 名称不匹配时，Prepr 将无法把文件映射到对应 Entity。保持所有

ref

稳定；文件之间的交叉引用都通过它进行。

What an import changes

import 会产生哪些变更

Before the user imports, give an impact assessment that names the target environment and says whether it is production:

every entity that will be overwritten (it has a matching file);
every entity that will be created (a file without a match);
every entity that will be deleted (no file, and no content uses it);
every field that disappears from an overwritten entity. Removing a field removes its content, and there is no undo.

With MCP connected, build this list by comparing

list_schema

and

get_schema_entity

with the files, matched as in Drift. Without MCP, ask the user to export the target to a branch and diff it.

Prepr validates the files and then shows its own import preview before anything changes. Ask the user to compare that preview with your assessment and to stop if they differ.

在用户执行 import 前，给出准确的影响评估，其中必须注明目标环境以及它是否为生产环境：

每个将被覆盖的 Entity（存在匹配文件）；
每个将被创建的 Entity（文件没有匹配项）；
每个将被删除的 Entity（没有对应文件，且没有内容使用它）；
被覆盖 Entity 中将消失的每个字段。移除字段会删除其中的内容，而且无法撤销。

连接 MCP 后，通过比较

list_schema

、

get_schema_entity

与文件，并按照 Drift 中描述的方式进行匹配，以生成此列表。如果没有 MCP，则请用户将目标环境 export 到一个分支，并对它执行 diff。

Prepr 会先验证文件，然后在实际更改任何内容之前显示自己的 import 预览。请用户将该预览与你的影响评估进行比较；如果两者不一致，请停止操作。

What direct sync does, if the user chooses it

用户选择直接同步时的行为

It only works between environments in the same organization.
Models in the target are overwritten when their singular name matches a source model, and fields are added or removed to match. Components, enumerations and remote sources are overwritten when their type name matches.
Target entities that are missing from the source are deleted when unused.
It cannot be undone once it has finished.

Name every entity that will be overwritten or deleted before the user runs it. An unreviewed direct sync to production is the worst case available; say so plainly.

它只能在同一组织的环境之间使用。
当 singular name 与源 Model 匹配时，目标 Model 会被覆盖，并按源 Model 添加或移除字段。Components、Enumerations 和 Remote Sources 在 type name 匹配时也会被覆盖。
源环境中不存在的目标 Entity，如果未被使用，也会被删除。
同步完成后无法撤销。

在用户运行直接同步前，列出每个将被覆盖或删除的 Entity。未经审查而直接同步到生产环境是可能发生的最糟糕情况；请明确而直白地告知用户。

Validate

验证

The validator checks that files are well-formed. It does not make a schema live, it does not judge the design (use review-schema for that), and it does not guarantee the import: Prepr's importer enforces more rules than the published spec. The known gaps and their errors: Validation is not import.

验证器只检查文件的格式是否正确。它不会让 Schema 生效，不评估设计质量（应使用 review-schema），而且不保证 import 一定成功：Prepr importer 执行的规则比已发布的规范更多。已知差异及对应错误见：验证不等于导入。

When an import fails

import 失败时

Import errors are often uninformative, and each guess costs a push and an import.

An empty error list is not a hint.
```
github.validation.failed
```
with
```
data: "[]"
```
says nothing about the cause. Say so, and ask the user for the detailed log from Prepr's log viewer before proposing a fix.
Check the known causes first. File names that do not match their entity names, and a
```
schema_version
```
that is not a released API version (see Validation is not import).
Read where the log stopped. The import reports each entity it completes. If it reached the last entity alphabetically, every entity passed on its own and the failure is a check on the whole schema.

import 错误通常没有太多信息，而每次猜测都意味着一次 push 和一次 import。

空错误列表并不能提供线索。
```
github.validation.failed
```
且
```
data: "[]"
```
无法说明失败原因。应明确指出这一点，并请用户提供 Prepr 日志查看器中的详细日志，然后再提出修复方案。
优先检查已知原因。 文件名与 Entity 名称不匹配，以及
```
schema_version
```
不是已发布的 API 版本（参见验证不等于导入）。
查看日志停止的位置。 import 会报告其完成的每个 Entity。如果日志按字母顺序推进到了最后一个 Entity，则说明每个 Entity 单独来看都通过了，失败来自针对整个 Schema 的某项检查。

Direction between environments

环境之间的同步方向

Both directions are legitimate and change opposite environments: production to development for a realistic test structure, development to production to ship reviewed changes. Ask which one is meant. With Git sync the direction shows in the diff before anything is applied.

两个方向都合理，但会改变源环境相对的另一端环境：将 production 同步到 development，以获得真实的测试结构；或将 development 同步到 production，以发布经过审查的变更。首先询问用户具体指哪个方向。使用 Git 同步时，在应用任何变更之前，可以通过 diff 看出同步方向。

Shared schema

共享 Schema

A shared schema lives at organization level, so a change reaches every environment that uses it. Promoting an entity needs the organization-level Schema permission, and an entity with unpromoted dependencies cannot be promoted until those are handled. Use the docs: https://docs.prepr.io/project-setup/architecture-scenarios/shared-schema

共享 Schema 位于组织级别，因此一项变更会影响所有使用它的环境。在环境之间提升 Entity 需要组织级别的 Schema 权限；如果某个 Entity 存在尚未提升的依赖项，则必须先处理这些依赖项。请参阅文档： https://docs.prepr.io/project-setup/architecture-scenarios/shared-schema

Verify

验证结果

After the user confirms the import ran:

Check the target with
```
get_schema_entity
```
(or ask the user to look) and compare it with the files.
Regenerate the project's GraphQL types, if it has code generation, and confirm it succeeds against the live schema.
Release the front-end code you held back and confirm it builds.

Do not call the task complete on a successful push.

用户确认 import 已执行后：

使用
```
get_schema_entity
```
检查目标环境（或请用户自行查看），并将其与文件进行比较。
如果项目使用代码生成，请重新生成项目的 GraphQL types，并确认其能够针对线上 Schema 成功生成。
发布之前暂缓的前端代码，并确认其构建成功。

不要因为 push 成功就将任务标记为完成。