gh-infra

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

gh-infra

gh-infra is a declarative GitHub infrastructure tool for repository settings and managed files.

Use this skill to choose the right resource kind, command flow, and operating pattern. Use the related skills for schema details.

Key characteristics:

No state file. GitHub is the source of truth.
Selective management. Omitted fields are left untouched.
Four resource kinds:
```
Repository
```
,
```
RepositorySet
```
,
```
File
```
,
```
FileSet
```
.
Supports both bootstrap import and reverse import into existing manifests.

gh-infra 是一款声明式 GitHub 基础设施工具，用于管理仓库设置和受控文件。

你可以使用本技能选择合适的资源类型、命令流和操作模式。如需了解 schema 详情，请使用相关技能。

核心特性：

无状态文件，GitHub 作为唯一可信源
选择性管理，未声明的字段将保持原有状态不变
四种资源类型：
```
Repository
```
、
```
RepositorySet
```
、
```
File
```
、
```
FileSet
```
支持启动导入和反向导入到现有清单中

Use This Skill For

适用场景

Choosing between
```
Repository
```
/
```
RepositorySet
```
/
```
File
```
/
```
FileSet
```
Running
```
import
```
,
```
validate
```
,
```
plan
```
, and
```
apply
```
Picking a central-management vs self-managed repo layout
Finding the right manifest skill for a concrete edit
Routing
```
import --into
```
work to the dedicated skill

在
```
Repository
```
/
```
RepositorySet
```
/
```
File
```
/
```
FileSet
```
之间做选型
执行
```
import
```
、
```
validate
```
、
```
plan
```
和
```
apply
```
命令
选择集中管理或自管理的仓库布局
为具体的编辑操作找到对应的清单技能
将
```
import --into
```
任务路由到专用技能

Related Skills

Task	Skill
Write/edit `Repository` or `RepositorySet` YAML	`repository-manifest`
Write/edit `File` or `FileSet` YAML	`file-manifest`
Set up CI workflows and auth	`ci-cd`
Pull live GitHub state back into existing manifests	`import-into`

任务	Skill
编写/编辑 `Repository` 或 `RepositorySet` YAML	`repository-manifest`
编写/编辑 `File` 或 `FileSet` YAML	`file-manifest`
配置 CI 工作流和鉴权	`ci-cd`
将 GitHub 实时状态拉取同步到现有清单中	`import-into`

Resource Selection

资源选型

Use:

```
Repository
```
for one repository's settings in one file
```
RepositorySet
```
for many repositories with shared defaults
```
File
```
for files in one repository
```
FileSet
```
for distributing shared files to many repositories

Every manifest starts with

apiVersion

and

kind

Single-repo resources:

yaml

apiVersion: gh-infra/v1
kind: Repository
metadata:
  owner: <github-owner>
  name: <repo-name>
spec:
  # ...

Set resources:

yaml

apiVersion: gh-infra/v1
kind: RepositorySet
metadata:
  owner: <github-owner>    # no "name" field
defaults:                   # RepositorySet: shared defaults
  spec: { ... }
repositories:               # RepositorySet: per-repo entries
  - name: <repo-name>
    spec: { ... }

yaml

apiVersion: gh-infra/v1
kind: FileSet
metadata:
  owner: <github-owner>    # no "name" field
spec:
  repositories: [...]       # FileSet: target repos
  files: [...]              # FileSet: files to distribute

A single YAML file can contain multiple

---

-separated documents. Anchors do not cross document boundaries.

使用规则：

单文件管理单个仓库的设置用
```
Repository
```
管理多个共享默认配置的仓库用
```
RepositorySet
```
管理单个仓库内的文件用
```
File
```
向多个仓库分发共享文件用
```
FileSet
```

所有清单都以

apiVersion

和

kind

开头。

单仓库资源示例：

yaml

apiVersion: gh-infra/v1
kind: Repository
metadata:
  owner: <github-owner>
  name: <repo-name>
spec:
  # ...

集合资源示例：

yaml

apiVersion: gh-infra/v1
kind: RepositorySet
metadata:
  owner: <github-owner>    # no "name" field
defaults:                   # RepositorySet: shared defaults
  spec: { ... }
repositories:               # RepositorySet: per-repo entries
  - name: <repo-name>
    spec: { ... }

yaml

apiVersion: gh-infra/v1
kind: FileSet
metadata:
  owner: <github-owner>    # no "name" field
spec:
  repositories: [...]       # FileSet: target repos
  files: [...]              # FileSet: files to distribute

单个 YAML 文件可包含多个用

---

分隔的文档。锚点不能跨文档边界生效。

Command Workflow

命令工作流

Default workflow:

text

import -> edit YAML -> validate -> plan -> apply

默认工作流：

text

import -> edit YAML -> validate -> plan -> apply

import

Bootstrap a manifest from live GitHub state:

bash

gh infra import <owner/repo>

从 GitHub 实时状态引导生成清单：

bash

gh infra import <owner/repo>

validate

Validate syntax and schema without contacting GitHub:

bash

gh infra validate [path...]

无需连接 GitHub 即可校验语法和 schema：

bash

gh infra validate [path...]

plan

Show diff against live GitHub state:

bash

gh infra plan [path...]

Use

--ci

for drift-detection workflows.

展示与 GitHub 实时状态的差异对比：

bash

gh infra plan [path...]

可使用

--ci

参数执行漂移检测工作流。

apply

Apply changes to GitHub:

bash

gh infra apply [path...]

Use

--auto-approve

in CI.

--force-secrets

re-sends all declared secrets.

将变更应用到 GitHub：

bash

gh infra apply [path...]

在 CI 环境中可使用

--auto-approve

参数。

--force-secrets

参数会重新发送所有声明的密钥。

Path Behavior

路径规则

For

validate

plan

, and

apply

No argument or
```
.
```
: read
```
*.yaml
```
and
```
*.yml
```
in the current directory
File path: read that file only
Directory path: read top-level
```
*.yaml
```
and
```
*.yml
```
only
Multiple paths:
```
gh infra plan ./repos/ ./files/
```
— manifests from all paths are combined
Overlapping paths (e.g.,
```
.
```
and
```
./repos/
```
) are rejected
Subdirectories are not scanned
Unknown YAML kinds are skipped unless
```
--fail-on-unknown
```
is set

对于

validate

、

plan

和

apply

命令：

无参数或传入
```
.
```
：读取当前目录下的所有
```
*.yaml
```
和
```
*.yml
```
文件
传入文件路径：仅读取指定文件
传入目录路径：仅读取目录顶层的
```
*.yaml
```
和
```
*.yml
```
文件
传入多个路径：例如
```
gh infra plan ./repos/ ./files/
```
— 会合并所有路径下的清单
重叠路径（例如
```
.
```
和
```
./repos/
```
）会被拒绝
不会扫描子目录
除非设置了
```
--fail-on-unknown
```
参数，否则会跳过未知 YAML 类型的文件

Common Patterns

常用模式

Central management repo: keep org-wide manifests in
```
repos/
```
and
```
files/
```
Self-managed repo: keep one manifest inside the managed repository and auto-apply on merge

Read references/patterns.md for layout guidance.

集中管理仓库：将组织级别的清单保存在
```
repos/
```
和
```
files/
```
目录下
自管理仓库：在被管理的仓库中保存一份清单，合并后自动执行 apply 操作

阅读 references/patterns.md 获取布局指引。

后续阅读

Command details: references/commands.md
Operating patterns: references/patterns.md

命令详情：references/commands.md
操作模式：references/patterns.md

Example Multi-Doc File

多文档文件示例

yaml

apiVersion: gh-infra/v1
kind: Repository
metadata:
  owner: my-org
  name: my-repo
spec:
  visibility: public
---
apiVersion: gh-infra/v1
kind: File
metadata:
  owner: my-org
  name: my-repo
spec:
  files:
    - path: .github/CODEOWNERS
      content: |
        * @username
  via: push

yaml

apiVersion: gh-infra/v1
kind: Repository
metadata:
  owner: my-org
  name: my-repo
spec:
  visibility: public
---
apiVersion: gh-infra/v1
kind: File
metadata:
  owner: my-org
  name: my-repo
spec:
  files:
    - path: .github/CODEOWNERS
      content: |
        * @username
  via: push

gh-infra

Original

Translation

gh-infra

gh-infra

Use This Skill For

适用场景

Related Skills

相关技能

Resource Selection

资源选型

Command Workflow

命令工作流

import

import

validate

validate

plan

plan

apply

apply

Path Behavior

路径规则

Common Patterns

常用模式

Read Next

后续阅读

Example Multi-Doc File

多文档文件示例