Skip to content

Resources / Repository

Repository

Repository manages a single GitHub repository — its description, visibility, topics, labels, features, merge strategy, branch protection rules, rulesets, secrets, variables, environments, and Actions settings.

Example
apiVersion: gh-infra/v1
kind: Repository
metadata:
name: my-project
owner: babarot
reconcile:
rulesets: authoritative
labels: authoritative
spec:
description: "My awesome project"
homepage: "https://example.com"
visibility: public
topics: [go, cli]
labels:
- name: kind/bug
color: d73a4a
description: "A bug; unintended behavior"
- name: kind/feature
color: "425df5"
description: "A feature request"
features:
issues: true
wiki: false
merge_strategy:
allow_squash_merge: true
auto_delete_head_branches: true
rulesets:
- name: protect-main
enforcement: active
conditions:
ref_name:
include: ["refs/heads/main"]
rules:
pull_request:
required_approving_review_count: 1
non_fast_forward: true
secrets:
- name: DEPLOY_TOKEN
value: "${ENV_DEPLOY_TOKEN}"
variables:
- name: APP_ENV
value: production
actions:
enabled: true
allowed_actions: selected
sha_pinning_required: true
workflow_permissions: read
can_approve_pull_requests: false
selected_actions:
github_owned_allowed: true
patterns_allowed: ["actions/*"]
metadata:
owner: babarot # GitHub owner or organization
name: my-project # Repository name

The combination of owner and name identifies the target repository (babarot/my-project).

Field Description
description Repository description
homepage URL displayed on the repo page
visibility public, private, or internal — see General Settings
archived Archive (read-only) or unarchive — see General Settings
topics GitHub topics for discoverability
labels Repository issue/PR labels — see Labels
label_sync Deprecated label sync mode: use reconcile.labels instead — see Labels
features Toggle issues, projects, wiki, discussions, pull requests — see General Settings
merge_strategy Merge commit, squash, rebase options — see General Settings
branch_protection Classic branch protection rules — see Branch Protection
rulesets Modern rulesets with enforcement modes and bypass actors — see Rulesets
secrets GitHub Actions secrets (via ${ENV_*} references) — see Secrets & Variables
variables Repository variables — see Secrets & Variables
environments Deployment environments: branch policies, reviewers, wait timer, variables and secrets — see Environments
actions GitHub Actions permissions, SHA pinning, workflow defaults, and fork PR policy — see Actions
pages GitHub Pages: build type, source branch, custom domain, HTTPS — see Pages

All fields are optional — declare only what you want to manage. Fields not present in the YAML are left unchanged on GitHub. The one exception is spec.actions.enabled: when managing any other Actions setting, GitHub requires enabled to be sent too. See Actions.

By default, collection fields are managed additively: gh-infra creates or updates entries declared in YAML and leaves undeclared GitHub resources untouched.

Use top-level reconcile to make selected collections match YAML exactly:

reconcile:
rulesets: authoritative
labels: additive
branch_protection: additive
spec:
rulesets:
- name: protect-main
target: branch
rules:
non_fast_forward: true
Field Modes Description
reconcile.labels additive, authoritative Controls how spec.labels is compared with existing GitHub labels
reconcile.rulesets additive, authoritative Controls how spec.rulesets is compared with existing GitHub rulesets
reconcile.branch_protection additive, authoritative Controls how spec.branch_protection is compared with existing classic branch protection rules
reconcile.deployment_branch_policies additive, authoritative Controls how the custom_branch_policies of each environment in spec.environments are compared with its patterns on GitHub — see Environments

additive is the default. authoritative deletes remote entries that are not declared in YAML, but only when the corresponding spec collection is present. If spec.rulesets, spec.branch_protection, or spec.labels is omitted, that collection is unmanaged even when reconcile has a policy for it.

To delete all labels, rulesets, or branch protection rules, use authoritative with an empty list:

reconcile:
rulesets: authoritative
spec:
rulesets: []

labels: null, labels:, rulesets: null, rulesets:, branch_protection: null, and branch_protection: are invalid. Use an empty list when you mean an empty managed collection.

Use Repository when you want to manage one repo’s settings in a dedicated YAML file. This is the simplest resource kind and the starting point for most users.

It works best when:

  • Each repo has its own distinct settings — different branch protection rules, different topics, different merge strategies.
  • You want per-repo change tracking — each file maps to one repo, so git blame tells you exactly who changed what and when.
  • You’re managing a small number of repos — for 1–5 repos, separate files are easy to maintain.

If you find yourself copying the same settings across many files, consider RepositorySet instead.

If a YAML manifest references a repository that doesn’t exist, plan shows it as a new resource, with what the same apply adds to it:

$ gh infra plan ./repos/
+ babarot/new-project will be created
+ repository babarot/new-project
+ ruleset "protect-main"
+ name protect-main
+ TOKEN (new)
+ labels
+ bug #ff0000
a label named like one of GitHub's default labels is updated instead of created
branch protection for main is applied by a later plan, once the branch exists

apply creates it with gh repo create, applying the settings, features, merge strategy, topics, security and Actions settings, and then the rulesets, secrets, variables, labels and milestones the plan shows, in the same run. archived: true is applied last.

A new repository is empty, so these are planned against nothing, with two exceptions:

  • Default labels: GitHub creates default labels in a new repository (bug, documentation, and others; an organization can change them). A label with the name of one of them is updated instead of created, so what the manifest leaves out of it, such as its description, stays as GitHub made it. With reconcile.labels: authoritative, the default labels the manifest does not declare are deleted by the next plan and apply.
  • Branch protection: a new repository has no branch to protect. The next plan after the branch exists shows the protection, and apply adds it. Rulesets do not need a branch and are applied at once.
  • Environment reviewers: GitHub drops a reviewer who cannot read the repository, and in a new one only its owner can. Other reviewers are added by a later plan, once they have access (see Environments).
  • Pages: a new repository has no commits to build a site from. The next plan enables it (see Pages).

The -o json and -o markdown plans list these notes as warnings for the repository. FileSets for the new repository are applied after it is created. The repository has no commits then, so a FileSet with via: pull_request is planned and applied as a push for it (see Empty repositories).

gh-infra does not support repository deletion. Without a state file, there is no way to distinguish “removed from YAML” from “never managed” — and repository deletion is irreversible.

To delete a repository, use gh repo delete directly.