repository-manifest

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Repository Manifest Reference

仓库清单参考

Use this skill when editing repository-side manifests. Keep the body small and load references only as needed.

编辑仓库侧清单时使用此Skill。保持内容精简，仅按需加载参考文档。

Core Rules

核心规则

All
```
spec
```
fields are optional. Omitted fields are left unchanged on GitHub.
```
Repository
```
manages one repository.
```
RepositorySet
```
manages many repositories with shared
```
defaults
```
.
For new setups, prefer
```
rulesets
```
over classic
```
branch_protection
```
.
Secret values must use
```
${ENV_*}
```
indirection, never literal secrets.

所有
```
spec
```
字段均为可选。省略的字段在GitHub上会保持原有值不变。
```
Repository
```
用于管理单个仓库。
```
RepositorySet
```
通过共享
```
defaults
```
配置管理多个仓库。
新配置优先使用
```
rulesets
```
而非传统的
```
branch_protection
```
。
密钥值必须使用
```
${ENV_*}
```
间接引用，绝对不要直接填写明文密钥。

Repository

yaml

apiVersion: gh-infra/v1
kind: Repository
metadata:
  owner: my-org
  name: my-repo
spec:
  # declare only managed fields

Read these references as needed:

General settings and lifecycle: references/general.md
Labels and label sync: references/labels.md
Actions settings and validation traps: references/actions.md
Rulesets and branch protection: references/protection.md
Secrets and variables: references/secrets-variables.md

yaml

apiVersion: gh-infra/v1
kind: Repository
metadata:
  owner: my-org
  name: my-repo
spec:
  # declare only managed fields

按需阅读以下参考文档：

通用配置与生命周期: references/general.md
标签与标签同步: references/labels.md
Actions配置与验证陷阱: references/actions.md
规则集与分支保护: references/protection.md
密钥与变量: references/secrets-variables.md

RepositorySet

Use

RepositorySet

when many repositories share defaults.

yaml

apiVersion: gh-infra/v1
kind: RepositorySet
metadata:
  owner: my-org

defaults:
  spec:
    visibility: public
    features:
      wiki: false
    merge_strategy:
      allow_squash_merge: true
      allow_rebase_merge: false
      auto_delete_head_branches: true
    rulesets:
      - name: protect-main
        target: branch
        enforcement: active
        conditions:
          ref_name:
            include: ["refs/heads/main"]
        rules:
          pull_request:
            required_approving_review_count: 1
          non_fast_forward: true

repositories:
  - name: repo-a
    spec:
      description: "Service A"
      topics: [go, api]

  - name: repo-b
    spec:
      description: "Service B"
      topics: [python, cli]
      features:
        wiki: true

Override behavior matters:

Scalars are replaced
Lists are replaced entirely
Maps are merged by key

This means

labels

replace the default list, while

label_sync

replaces as a scalar.

Read references/repository-set.md for the exact merge rules.

当多个仓库需要共享默认配置时使用

RepositorySet

。

yaml

apiVersion: gh-infra/v1
kind: RepositorySet
metadata:
  owner: my-org

defaults:
  spec:
    visibility: public
    features:
      wiki: false
    merge_strategy:
      allow_squash_merge: true
      allow_rebase_merge: false
      auto_delete_head_branches: true
    rulesets:
      - name: protect-main
        target: branch
        enforcement: active
        conditions:
          ref_name:
            include: ["refs/heads/main"]
        rules:
          pull_request:
            required_approving_review_count: 1
          non_fast_forward: true

repositories:
  - name: repo-a
    spec:
      description: "Service A"
      topics: [go, api]

  - name: repo-b
    spec:
      description: "Service B"
      topics: [python, cli]
      features:
        wiki: true

覆盖规则说明：

标量值会被直接替换
列表会被完全覆盖
映射会按键合并

这意味着

labels

会替换默认列表，而

label_sync

作为标量会直接被替换。

阅读references/repository-set.md了解确切的合并规则。

High-Value Gotchas

常见踩坑提示

```
actions.enabled
```
is required when setting any other
```
actions.*
```
field

actions.selected_actions

is valid only with

allowed_actions: selected

```
label_sync: mirror
```
deletes unmanaged labels; review
```
plan
```
carefully
for
```
gh infra import --into
```
, use the dedicated
```
import-into
```
skill
Repository deletion is not supported

设置任何其他
```
actions.*
```
字段时必须配置
```
actions.enabled
```

actions.selected_actions

仅在

allowed_actions: selected

时生效

```
label_sync: mirror
```
会删除未被管理的标签，请务必仔细检查
```
plan
```
结果
执行
```
gh infra import --into
```
时，请使用专门的
```
import-into
```
Skill
不支持仓库删除操作

Verification

验证

bash

gh infra validate <path>
gh infra plan <path>

bash

gh infra validate <path>
gh infra plan <path>