| name | repository-manifest |
| description | Complete YAML schema reference for Repository and RepositorySet resources. Use when writing or editing manifests for repo settings, labels, actions, branch protection, rulesets, secrets, variables, or repository defaults.
|
Repository Manifest Reference
Use this skill when editing repository-side manifests. Keep the body small and load references only as needed.
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.
Repository
apiVersion: gh-infra/v1
kind: Repository
metadata:
owner: my-org
name: my-repo
reconcile:
rulesets: additive
labels: additive
spec:
Read these references as needed:
RepositorySet
Use RepositorySet when many repositories share defaults.
apiVersion: gh-infra/v1
kind: RepositorySet
metadata:
owner: my-org
defaults:
reconcile:
rulesets: authoritative
labels: additive
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, ]
[, ]
Override behavior matters:
- Scalars are replaced
- Simple lists are replaced entirely
- Keyed collections are merged by key
- Maps are merged by key
This means topics replace the default list, while labels and reconcile.labels are merged by key/collection.
Read references/repository-set.md for the exact merge rules.
High-Value Gotchas
actions.enabled is required when setting any other actions.* fieldactions.selected_actions is valid only with allowed_actions: selectedreconcile.labels: authoritative, reconcile.rulesets: authoritative, and reconcile.branch_protection: authoritative delete undeclared remote entries; review plan carefullyreconcile without a corresponding spec collection is no-op; a collection is managed only when it appears in speclabel_sync: mirror is deprecated; use reconcile.labels: authoritative- for
gh infra import --into, use the dedicated import-into skill
- Repository deletion is not supported
Verification
gh infra validate <path>
gh infra plan <path>
