babarot/gh-infra/repository-manifest

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:           # optional; controls collection reconciliation
  rulesets: additive # additive (default) | authoritative
  labels: additive
spec:
  # declare only managed fields

Read these references as needed:

• General settings and lifecycle: references/general.md
• Labels and reconcile mode: 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
• Security (Dependabot, vulnerability alerts): references/security.md

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, api]
 
  - name: repo-b
    spec:
      description: "Service B"
      topics: [python, cli]
      features:
        wiki: true

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.* field
• actions.selected_actions is valid only with allowed_actions: selected
• reconcile.labels: authoritative, reconcile.rulesets: authoritative, and reconcile.branch_protection: authoritative delete undeclared remote entries; review plan carefully
• reconcile without a corresponding spec collection is no-op; a collection is managed only when it appears in spec
• label_sync: mirror is deprecated; use reconcile.labels: authoritative
• fields left out of the manifest are left as they are on GitHub (rulesets, branch protection, milestones, label descriptions, selected actions): to manage part of a ruleset, write only that part
• in a RepositorySet entry, labels: [] (or rulesets, branch_protection, secrets, variables, topics, milestones) means none: the defaults are not inherited; under reconcile.<collection>: authoritative it deletes every item on that repo. An entry cannot drop a single default item; change the defaults or use a standalone Repository (#215)
• label names are matched ignoring case, as on GitHub; changing only the case renames the label
• for gh infra import --into, use the dedicated import-into skill
• Repository deletion is not supported
• plan reads only the settings the manifest sets; a managed setting the token cannot read (403) fails the repo with cannot read ... instead of being treated as empty (rulesets on GitHub Free private repos fail this way)

Verification

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