Config reference

A config file names the repositories to manage and a shared block of sections applied to every one of them. Every key is validated, so a typo becomes a load error, not a silent no-op — unknown fields anywhere in the schema are rejected.

File anatomy

A config lists repos: — owner/repo strings, each validated to be in that exact form — plus the shared sections below. All sections are optional, but the repos: list must have at least one entry.

repos:
  - octocat/hello-world
  - octocat/spoon-knife

settings:
  description: "Example repository"
  private: false
  has_issues: true
  delete_branch_on_merge: true

actions:
  enabled: true
  allowed_actions: all
  can_approve_pull_request_reviews: true

labels:
  - name: bug
    color: d73a4a
    description: Something isn't working
  - name: needs-triage
    color: fbca04

collaborators:
  - username: octocat
    permission: admin

webhooks:
  - url: https://example.com/hooks/ci
    events: [push, pull_request]
    secret_from_env: CI_WEBHOOK_SECRET

secrets:
  - name: DEPLOY_TOKEN
    value_from_env: DEPLOY_TOKEN

variables:
  - name: ENVIRONMENT
    value: production

rulesets:
  - name: main-branch-protection
    target: branch
    rules:
      - type: pull_request
        required_approving_review_count: 1

Section authority

rulesets

Repository rulesets are declared under rulesets:, one entry per ruleset, matched to live rulesets by name and reconciled to exactly the declared spec. The shape is large enough — target, enforcement, bypass actors, conditions, and a dozen rule types — that it has its own page: see the rulesets reference.

settings

Repository-level settings. Every field is optional; a field left unset is left unmanaged on the repo (not reset to a default).

actions

Actions enablement/policy and workflow permissions — three separate GitHub API endpoints that PyGithub doesn't model, driven directly. Every field is optional; a field left unset is left unmanaged, and an unmanaged field of a pair (e.g. enabled vs. allowed_actions) is written back with its live value so the PUT doesn't clear it.

actions:
  enabled: true
  allowed_actions: selected
  selected_actions:
    github_owned_allowed: true
    verified_allowed: true
    patterns_allowed: ["astral-sh/*"]
  default_workflow_permissions: read
  can_approve_pull_request_reviews: true

labels

Issue and PR labels, matched by name. Exact-set semantics apply: labels on the repo that aren't in the list are deleted.

collaborators

Direct collaborators and their permission level, matched by username.

webhooks

Repository webhooks, matched by url.

secrets

Actions secrets. Each entry needs a name plus exactly one of value or value_from_env — providing both, or neither, is a validation error.

Secret values are write-only: GitHub never returns them, so apply never diffs the current value against the declared one. By default a secret already present on the repo is left alone; pass --force-secrets to re-push every declared secret, e.g. to rotate one. Values are never printed in plans.

variables

Actions repository variables — same shape as secrets, but not sensitive.

Variable values are readable on GitHub and shown in plain text in plans. Unlike secrets, an existing variable is only pushed when its resolved value actually differs from what's on the repo.

Composing with extends

A config can extends: one or more base files:

extends: ../base/org-defaults.yaml
# or
extends:
  - ../base/org-defaults.yaml
  - ../base/security-baseline.yaml

Paths are relative to the file that declares them, and extends: is recursive — a base can itself extend another base. Bases merge underneath the file that extends them, in list order, and the extending file's own content merges on top of all of them last.

Merge rules:

• Scalars (strings, bools, individual settings/actions fields): the override wins outright.
• Keyed lists — rulesets, labels, secrets, and variables by name; collaborators by username; webhooks by url — merge item-by-item: an override item sharing a base item's key replaces that item in place (keeping its position), and an override item with a new key is appended.

A circular extends chain (A extends B extends A) is detected and rejected as a config error rather than looping forever.

By convention, *.yml files in the config directory are the applied configs — each with its own repos: list, picked up by the CLI's config-dir glob — while *.yaml files are base layers that only exist to be pulled in via extends:. Neither extension is enforced by the schema; it's a naming convention this repo relies on to tell the two apart at a glance.

Environment-sourced values

value_from_env (secrets, variables) and secret_from_env (webhooks) are resolved when a plan or apply actually runs — not when the config is loaded and validated, so schema checks don't require any secrets to be present in the environment.