Config Schema Reference

The full JSON Schema for xfg configuration files is available at:

https://raw.githubusercontent.com/anthony-spruyt/xfg/main/config-schema.json

Using the Schema

In VS Code

Add a comment at the top of your config file:

# yaml-language-server: $schema=https://raw.githubusercontent.com/anthony-spruyt/xfg/main/config-schema.json
files:
  # ...
repos:
  # ...

Or configure in .vscode/settings.json:

{
  "yaml.schemas": {
    "https://raw.githubusercontent.com/anthony-spruyt/xfg/main/config-schema.json": [
      "**/sync-config.yaml",
      "**/config-sync.yaml"
    ]
  }
}

Schema Structure

Root Object

Field	Type	Required	Description
id	string	Yes	Unique config identifier (alphanumeric, -, _)
files	object	*	Map of filenames to file configs
groups	object	*	Named config groups referenced by repos
conditionalGroups	array	*	Groups that activate based on repo group membership
repos	array	Yes	List of repository configurations
settings	object	*	Repository settings (rulesets, labels, variables, etc.)
secrets	object	No	GitHub Actions secrets (root-level, synced via xfg secrets sync)
prOptions	PROptions	No	Global PR merge options
prTemplate	string	No	Custom PR body template
githubHosts	array	No	GitHub Enterprise Server hostnames
deleteOrphaned	boolean	No	Global default for orphan file deletion

files/settings/groups requirement

At least one of files, settings, groups, or conditionalGroups must be present. The sync command requires files defined in root files, in a group, or in a conditional group. The settings command requires settings at root, repo, group, or conditional group level.

Multi-file directory config

When passing a directory to -c, xfg recursively scans subdirectories for .yaml and .yml files. See Multi-File Configuration for ordering rules and constraints.

Settings Object

The settings object (at root, group, or repo level) supports the following fields:

Field	Type	Description
rulesets	object	GitHub rulesets keyed by name
repo	object	GitHub repository settings
labels	object	GitHub labels keyed by name
codeScanning	object	GitHub code scanning default setup
variables	object	GitHub Actions variables keyed by name (see below)
deleteOrphaned	boolean	Default for orphan deletion across all settings sub-types

Variables Field

The variables field in settings maps variable names to their string values. Two special keys control behavior:

Key	Type	Description
deleteOrphaned	boolean	Delete variables removed from config (independent of settings-level deleteOrphaned)
inherit	boolean	Set to false to discard all inherited variables (per-repo/group only)
VAR_NAME	string \| false	Variable value, or false to opt out of an inherited variable

See GitHub Variables for full details.

Secrets Object

The secrets object is at the root level (not under settings) and is synced via xfg secrets sync, not xfg sync. It maps secret names to SecretConfig objects:

Field	Type	Description
deleteOrphaned	boolean	Delete secrets removed from config
SECRET_NAME	object	SecretConfig with an env field (see below)

SecretConfig

Field	Type	Required	Description
env	string	Yes	Name of the environment variable holding the secret value

See Secrets for full details.

File Config

Field	Type	Required	Description
content	object/string/array	No	File content or @path/to/file ref
mergeStrategy	string	No	replace, append, prepend
createOnly	boolean	No	Only create if doesn't exist
executable	boolean	No	Mark file as executable
header	string/array	No	YAML header comment(s)
schemaUrl	string	No	YAML schema directive URL
template	boolean	No	Enable ${xfg:...} variable support
vars	object	No	Custom template variables
deleteOrphaned	boolean	No	Track file for orphan deletion

Group Config

Field	Type	Required	Description
extends	string \| string[]	No	Parent group name(s) to inherit from
files	object	No	Files defined or overridden by this group
prOptions	PROptions	No	PR options for repos using this group
settings	object	No	Settings for repos using this group (supports inherit)

Groups support extends (inherit from parent groups), inherit: false (discard accumulated files), file: false (remove a file), and full file config or override objects.

Conditional Group Config

Field	Type	Required	Description
when	object	Yes	Condition that determines when this group activates
files	object	No	Files defined or overridden (same capabilities as groups)
prOptions	PROptions	No	PR options for matching repos
settings	object	No	Settings for matching repos (supports inherit)

The when clause:

Field	Type	Required	Description
allOf	string[]	*	All listed groups must be present on the repo
anyOf	string[]	*	At least one listed group must be present

At least one of allOf or anyOf is required. When both are specified, both conditions must be satisfied. See Groups — Conditional Groups.

Repo Config

Field	Type	Required	Description
git	string/array	Yes	Git URL(s)
files	object	No	Per-repo file overrides
groups	string[]	No	Group names to apply (merged in order)
settings	object	No	Per-repo settings (rulesets, labels, repo settings)
prOptions	PROptions	No	Per-repo PR options
upstream	string	No	Fork from this URL if target doesn't exist
source	string	No	Migrate from this URL if target doesn't exist

upstream and source are mutually exclusive

See Repo Lifecycle for details.

Per-Repo File Override

Field	Type	Required	Description
content	object/string/array	No	Content overlay merged onto base
override	boolean	No	If true, ignore base content entirely
createOnly	boolean	No	Override root-level createOnly
executable	boolean	No	Override root-level executable
header	string/array	No	Override root-level header
schemaUrl	string	No	Override root-level schemaUrl
template	boolean	No	Override root-level template
vars	object	No	Per-repo template variables
deleteOrphaned	boolean	No	Override file-level deleteOrphaned

PR Options

Field	Type	Default	Description
merge	string	auto	manual, auto, force, direct
mergeStrategy	string	squash	merge, squash, rebase
deleteBranch	boolean	true	Delete branch after merge
bypassReason	string	-	Reason for bypass (Azure DevOps only)
labels	string[]	-	Labels to apply to created PRs (GitHub only)
branch	string	-	Branch name for sync PRs

Validation

The schema validates:

• Required fields (id, repos, at least one of files, settings, or groups)
• Command-specific requirements (see below)
• Enum values (mergeStrategy, merge, etc.)
• Content types (object for JSON/YAML, string/array for text files)
• File path security (no path traversal in file references)

Config Requirements

The xfg sync command accepts configs with files, settings, or both. At least one of files, settings, groups, or conditionalGroups must be present.