// Overview of gh-infra and command workflow (import, validate, plan, apply). Use when managing GitHub repository settings, labels, actions settings, rulesets, secrets, variables, or files declaratively via YAML manifests.
| name | gh-infra |
| description | Overview of gh-infra and command workflow (import, validate, plan, apply). Use when managing GitHub repository settings, labels, actions settings, rulesets, secrets, variables, or files declaratively via YAML manifests. |
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:
Repository, RepositorySet, File, FileSet.Repository / RepositorySet / File / FileSetimport, validate, plan, and applyimport --into work to the dedicated skill| 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 |
Use:
Repository for one repository's settings in one fileRepositorySet for many repositories with shared defaultsFile for files in one repositoryFileSet for distributing shared files to many repositoriesEvery manifest starts with apiVersion and kind.
Single-repo resources:
apiVersion: gh-infra/v1
kind: Repository
metadata:
owner: <github-owner>
name: <repo-name>
spec:
# ...
Set resources:
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: { ... }
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.
Default workflow:
import -> edit YAML -> validate -> plan -> apply
Bootstrap a manifest from live GitHub state:
gh infra import <owner/repo>
Validate syntax and schema without contacting GitHub:
gh infra validate [path...]
Show diff against live GitHub state:
gh infra plan [path...]
Use --ci for drift-detection workflows.
Apply changes to GitHub:
gh infra apply [path...]
Use --auto-approve in CI. --force-secrets re-sends all declared secrets.
For validate, plan, and apply:
.: read *.yaml and *.yml in the current directory*.yaml and *.yml onlygh infra plan ./repos/ ./files/ — manifests from all paths are combined. and ./repos/) are rejected--fail-on-unknown is setrepos/ and files/Read references/patterns.md for layout guidance.
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
Complete YAML schema reference for File and FileSet resources. Use when writing manifests to manage files (CODEOWNERS, LICENSE, CI workflows, etc.) in one or more repositories, including templating, patches, reconcile modes, delivery method, and import-into behavior.
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.
CI/CD integration patterns for gh-infra: auto-apply on merge, scheduled drift detection, self-managed vs central-management layouts, and authentication setup for GitHub Actions workflows.
Use when pulling live GitHub state back into existing gh-infra manifests with `gh infra import --into`, especially for write/patch/skip decisions, shared file sources, template-backed files, and import safety rules.
Use when running demo recordings, diagnosing recording failures, or regenerating GIFs from existing MP4s. Covers the Docker + VHS + ffmpeg pipeline.
Use when creating new VHS demo tapes or editing existing ones. Covers tape syntax, setup scripts, mock-gh data layout, and the checklist for adding a new demo end-to-end.