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

security

Repository security posture. Every field is optional and independently managed — each maps to its own GitHub endpoint, so a plan can show anywhere from zero to four separate changes for this section (secret scanning and push protection share one endpoint and are batched into a single change when either differs).

security:
  secret_scanning: true
  secret_scanning_push_protection: true
  vulnerability_alerts: true
  automated_security_fixes: true
  private_vulnerability_reporting: 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.

deploy_keys

Deploy keys, matched by key content (not title — GitHub allows duplicate titles, but key content is the real identity).

autolinks

Autolink references, matched by key_prefix — a prefix like TICKET- in commit messages and PR text is turned into a link using url_template.

autolinks:
  - key_prefix: "TICKET-"
    url_template: "https://example.atlassian.net/browse/TICKET-<num>"

pages

GitHub Pages configuration. Omitting pages: entirely leaves it unmanaged; declaring it with enabled: false disables Pages if it's currently on.

pages:
  build_type: legacy
  source: {branch: main, path: "/docs"}
  https_enforced: true

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.

environments

Deployment environments, matched by name: protection rules plus environment-scoped secrets/variables (same shape as the top-level sections above, but scoped to the environment).

Each reviewer is a User (by login) or a Team (by slug), resolved to the numeric ID GitHub's API requires when the plan runs — a Team reviewer requires an org-owned repository. login/slug must be a valid GitHub identifier (letters, digits, and internal hyphens only — no /), since the value is used directly in the resolution request.

environments:
  - name: production
    wait_timer: 10
    reviewers:
      - {type: User, login: octocat}
      - {type: Team, slug: platform}
    prevent_self_review: true
    deployment_branch_policy: {protected_branches: true}
    secrets:
      - {name: DEPLOY_TOKEN, value_from_env: PROD_DEPLOY_TOKEN}
    variables:
      - {name: REGION, value: us-east-1}

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, variables, and environments by name; collaborators by username; webhooks by url; deploy_keys by key; autolinks by key_prefix — 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.