Skip to content

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
id: config-schema
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 Default Description
id string No - Unique identifier for this config.
files object of fileConfig No - Map of target filenames to their configurations.
groups object of groupConfig No - Named configuration groups that repos can reference via 'groups: [...]'.
conditionalGroups conditionalGroupConfig[] No - Conditional groups that activate based on which groups a repo has.
repos repo[] No - List of repository configurations.
prOptions prOptions No - Global PR merge options.
prTemplate string No - Custom PR body template.
githubHosts string[] No - List of GitHub Enterprise Server hostnames.
deleteOrphaned boolean No false Global default for orphan deletion.
settings rootSettings No - Global repository settings including GitHub Rulesets.
  • id — Used to namespace managed files in .xfg.json manifest, allowing multiple configs to manage the same repo without conflicts.
  • files — Each file is synced to all repos by default.
  • groups — Groups create a merge chain: root → group1 → group2 → repo overrides. Each group can define files, prOptions, and settings.
  • conditionalGroups — Each entry has a 'when' clause (allOf/anyOf/noneOf) and the same files/prOptions/settings as regular groups. Merges after explicit groups, before repo overrides.
  • repos — When using directory-based config, repos can be split across multiple files. Directory-based config recursively scans subdirectories.
  • prOptions — Can be overridden per-repo.
  • prTemplate — Can be inline markdown or a file reference (@path/to/template.md relative to config file). Supports ${xfg:...} templating variables: ${xfg:pr.fileChanges} (bulleted file list), ${xfg:pr.fileCount}, ${xfg:pr.title}, plus all repo variables (repo.name, repo.owner, repo.fullName, etc.).
  • githubHosts — URLs matching these hosts will be treated as GitHub repositories instead of falling back to GitLab detection. Example: ['github.mycompany.com', 'ghe.internal.net']
  • deleteOrphaned — When true, files removed from the xfg config will be deleted from target repos (tracked via .xfg.json manifest). Can be overridden per-file or per-repo. Default: false
  • settings — Can be overridden per-repo. Settings are merged: per-repo rulesets override root rulesets with same name.

files/settings requirement

xfg sync accepts configs with files, settings, or both. A config needs files at root or in a group or conditional group, or settings with at least one entry 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.

Definitions

Every definition below is generated from config-schema.json. Prose guides live under Configuration.

fileConfig

Configuration for a single file to sync

Field Type Required Default Description
content object | string | string[] No - File content.
mergeStrategy replace | append | prepend | merge No replace Array merge strategy for this file.
createOnly boolean No false If true, only create this file if it doesn't already exist in the target repo.
header string | string[] No - Comment line(s) added at the top of YAML files ('# ' prefix) and .json5 files ('// ' prefix).
schemaUrl string No - YAML only.
executable boolean No - Mark the file as executable via git update-index --add --chmod=+x.
template boolean No false Enable xfg templating for this file.
vars object of string No - Custom template variables for this file.
deleteOrphaned boolean No false Track this file for orphan deletion.
  • content — Object for JSON/YAML files, string or string[] for text files. Use @path/to/file to reference external template files (paths relative to config file). Supports ${VAR} env interpolation; use $${VAR} to output literal ${VAR}. Omit for empty file.
  • mergeStrategy — 'replace' replaces arrays, 'append' adds overlay after base, 'prepend' adds overlay before base, 'merge' deep-merges items matched by identity key (type, actorId, actor_id). Default: replace
  • createOnly — Useful for files like .trivyignore or .prettierignore where you want to provide defaults but let repos customize. Default: false
  • header — Ignored for .json and text files.
  • schemaUrl — URL for yaml-language-server schema directive. Adds '# yaml-language-server: $schema=\' at the top of YAML files. For JSON files, use $schema property in content instead.
  • executable — Shell scripts (.sh) are auto-executable unless explicitly set to false. Non-.sh files can be marked executable by setting to true.
  • template — When true, ${xfg:variable} placeholders are replaced with repo-specific values. Available variables: repo.name, repo.owner, repo.fullName, repo.url, repo.platform, repo.host, file.name, date, and any custom vars. Use $${xfg:...} to output literal ${xfg:...}. Default: false
  • vars — Accessible as ${xfg:varName} when template: true. Root, group, conditional-group and per-repo vars merge per key, and later layers win.
  • deleteOrphaned — When true, if this file is removed from the config, it will be deleted from target repos. Tracked via .xfg.json manifest. Overrides global deleteOrphaned setting. Default: false

repo

Repository configuration

Field Type Required Default Description
git string | string[] Yes - Git repository URL(s).
files object of false | repoFileOverride No - Per-repo file overrides or exclusions.
groups string[] No - List of group names to apply to this repo.
prOptions prOptions No - Per-repo PR merge options.
settings repoSettings No - Per-repo settings including GitHub Rulesets.
upstream string No - Fork upstream repo if target doesn't exist.
source string No - Migrate from source repo if target doesn't exist.
  • git — Supports GitHub (git@github.com:owner/repo.git, https://github.com/owner/repo.git) and Azure DevOps formats
  • files — Keys must reference files defined in the root 'files' object. Set to false to exclude a file from this repo. Set inherit: false to skip all inherited files.
  • groups — Groups are merged in order: root → group1 → group2 → repo overrides. Group names must reference groups defined in the root 'groups' object.
  • prOptions — Overrides global prOptions.
  • settings — Merged with global settings: per-repo rulesets override root rulesets with same name.
  • upstream — When the target repo is missing, xfg forks from this URL instead of creating an empty repo. Mutually exclusive with 'source'. Supports SSH (git@host:owner/repo.git) and HTTPS (https://host/owner/repo.git) formats.
  • source — When the target repo is missing, xfg clones this repo with --mirror and pushes to the new target. Use for cross-platform migration (e.g., Azure DevOps to GitHub). Mutually exclusive with 'upstream'. Supports SSH and HTTPS formats.

upstream and source are mutually exclusive

See Repo Lifecycle for details.

prOptions

PR merge behavior options

Field Type Required Default Description
inherit boolean No - Set to false to drop every inherited prOptions field (including ai), then apply this layer's own.
merge manual | auto | force | direct No auto Merge mode: 'manual' leaves PR open for review, 'auto' enables auto-merge when checks pass, 'force' bypasses requirements using admin privileges, 'direct' pushes directly to default branch without creating a PR.
mergeStrategy merge | squash | rebase No squash How to merge the PR: 'merge' creates a merge commit, 'squash' squashes all commits, 'rebase' rebases commits onto base.
deleteBranch boolean No true Delete the source branch after merge completes.
bypassReason string No - Reason for bypassing policies (Azure DevOps only, used when merge=force).
labels string[] | arrayMergeDirective No - Labels to apply to created PRs/MRs.
branch string No - Branch name for sync PRs.
ai boolean | aiOptions No - AI-generated conventional commit messages and PR descriptions. true = Anthropic with defaults; false turns it off (e.g. per repo).
  • inherit — Not valid at root level. Default: true
  • merge — Default: auto
  • mergeStrategy — Default: squash
  • deleteBranch — Default: true
  • bypassReason — Default: Automated config sync via xfg
  • labels — Labels must exist on the target repository.
  • branch — Per-repo overrides group, group overrides global. CLI --branch flag overrides all.
  • ai — Falls back to the default message on any AI error. Disabled by --no-ai.

aiOptions

See AI Commit Messages for setup and privacy notes.

AI provider settings for generated commit messages and PR descriptions

Field Type Required Default Description
inherit boolean No - Set to false to drop every inherited ai field (fallback included), then apply this layer's own.
provider anthropic | openai No anthropic 'anthropic' uses the Claude Messages API.
model string No - Model id.
baseUrl string No - API base URL, e.g.
baseUrlEnv string No - Name of the env var holding the API base URL, for when the URL must not be written in config.
apiKeyEnv string No - Name of the env var holding the API key.
headersEnv object of string No - Extra HTTP headers sent with the AI request, as header name to env var name pairs.
prompt string No - Extra instructions appended to the built-in system prompt
maxDiffChars integer No 20000 Maximum diff characters sent to the provider, shared fairly across files.
fallback aiFallbackOptions No - Provider to try when this one fails for any reason.
  • inherit — Not valid at root level. Default: true
  • provider — 'openai' uses any OpenAI-compatible Chat Completions API (OpenAI, Ollama, Azure OpenAI, LiteLLM). Default: anthropic
  • model — Default for anthropic: claude-haiku-4-5. Required for openai.
  • baseUrl — http://localhost:11434/v1 for Ollama. With openai, a baseUrl makes the API key optional.
  • baseUrlEnv — Mutually exclusive with baseUrl. If the env var is unset, empty or not an http(s) URL, this provider is skipped with a warning. Cannot name a credential xfg uses elsewhere such as GH_TOKEN.
  • apiKeyEnv — Default: ANTHROPIC_API_KEY or OPENAI_API_KEY
  • headersEnv — Values are never written in config. If an env var is unset or empty, this provider is skipped with a warning. Cannot name a credential xfg uses elsewhere such as GH_TOKEN, nor a header xfg sets itself.
  • maxDiffChars — Default: 20000
  • fallback — If it fails too, the default message is used.

aiFallbackOptions

Same fields as aiOptions except fallback. See Fallback provider.

Fallback AI provider, tried when the primary fails for any reason (missing key or header env var, network error, timeout, non-2xx status, invalid reply). prompt and maxDiffChars default to the primary's. One level only.

Field Type Required Default Description
provider anthropic | openai No anthropic 'anthropic' uses the Claude Messages API.
model string No - Model id.
baseUrl string No - API base URL, e.g.
baseUrlEnv string No - Name of the env var holding the API base URL, for when the URL must not be written in config.
apiKeyEnv string No - Name of the env var holding the API key.
headersEnv object of string No - Extra HTTP headers sent with the AI request, as header name to env var name pairs.
prompt string No - Extra instructions appended to the built-in system prompt
maxDiffChars integer No 20000 Maximum diff characters sent to the provider, shared fairly across files.
  • provider — 'openai' uses any OpenAI-compatible Chat Completions API (OpenAI, Ollama, Azure OpenAI, LiteLLM). Default: anthropic
  • model — Default for anthropic: claude-haiku-4-5. Required for openai.
  • baseUrl — http://localhost:11434/v1 for Ollama. With openai, a baseUrl makes the API key optional.
  • baseUrlEnv — Mutually exclusive with baseUrl. If the env var is unset, empty or not an http(s) URL, this provider is skipped with a warning. Cannot name a credential xfg uses elsewhere such as GH_TOKEN.
  • apiKeyEnv — Default: ANTHROPIC_API_KEY or OPENAI_API_KEY
  • headersEnv — Values are never written in config. If an env var is unset or empty, this provider is skipped with a warning. Cannot name a credential xfg uses elsewhere such as GH_TOKEN, nor a header xfg sets itself.
  • maxDiffChars — Default: 20000

repoFileOverride

Per-repo override for a specific file

Field Type Required Default Description
content object | string | string[] No - Content overlay merged onto the file's base content.
override boolean No false If true, use only this content and skip merging with base.
createOnly boolean No - Override the root-level createOnly setting for this specific repo
header string | string[] No - Override the root-level header for this specific repo.
schemaUrl string No - YAML only.
executable boolean No - Override the root-level executable setting for this specific repo.
template boolean No - Override the root-level template setting for this specific repo.
vars object of string No - Per-repo custom template variables.
deleteOrphaned boolean No - Override the file-level or global deleteOrphaned setting for this specific repo.
  • content — Use @path/to/file to reference external template files. Must match the content type of the root file definition.
  • override — Default: false
  • header — Applies to YAML and .json5 files, ignored for .json and text files.
  • schemaUrl — Override the root-level schemaUrl for this specific repo. For JSON files, use $schema property in content instead.
  • executable — Set to true to mark executable, or false to disable auto-executable behavior for .sh files.
  • template — Set to true to enable xfg templating, or false to disable it.
  • vars — These merge per key with the root, group and conditional-group vars for this file and win over them. Accessible as ${xfg:varName} when template: true.
  • deleteOrphaned — Set to true to enable orphan tracking, or false to disable it for this repo.

groupConfig

Configuration group that can define files, prOptions, and settings. Referenced by repos via 'groups: [groupName]'.

Field Type Required Default Description
extends string | string[] No - Parent group name(s) to inherit files, settings, and PR options from.
files object of false | fileConfig | repoFileOverride No - Files defined or overridden by this group.
prOptions prOptions No - PR merge options for repos using this group.
settings repoSettings No - Settings for repos using this group.
  • extends — Accepts a single group name or an array of group names. Parents are merged before the child group.
  • files — Keys are filenames. Set to false to remove an inherited file. Set inherit: false to discard all accumulated files from prior layers.
  • prOptions — Overrides root prOptions, can be overridden by repo prOptions.
  • settings — Supports inherit: false on rulesets/labels sub-sections. Merged between root and repo settings.

conditionalGroupConfig

Conditional group that activates based on which groups a repo has. Has a 'when' clause and the same files/prOptions/settings as regular groups.

Field Type Required Default Description
when any Yes - Condition that determines when this group activates.
files object of false | fileConfig | repoFileOverride No - Files defined or overridden by this conditional group.
prOptions prOptions No - PR merge options for repos matching this condition.
settings repoSettings No - Settings for repos matching this condition.
  • when — At least one of allOf, anyOf, or noneOf is required.
  • files — Same capabilities as regular group files.
  • settings — Supports inherit: false on rulesets/labels sub-sections.

See Groups — Conditional Groups.

codeScanningSettings

GitHub code scanning default setup configuration. Fields merge with the inherited block; set inherit: false to drop what it would inherit, for example to go back to auto-detected languages.

Field Type Required Default Description
inherit boolean No - Set to false to drop every inherited code scanning setting, then apply this layer's own.
state configured | not-configured No - Enable or disable code scanning default setup.
querySuite default | extended No - Query suite to use: 'default' for standard queries, 'extended' for additional queries
languages actions | c-cpp | csharp | go | java-kotlin | javascript-typescript | python | ruby | swift[] | arrayMergeDirective No - Languages to analyze.
  • inherit — Not valid at root level. Default: true
  • state — Some layer must set it.
  • languages — If omitted, GitHub auto-detects languages in the repository. A layer that omits it inherits the parent's list; a plain list replaces it, and inherit: false goes back to auto-detect.

actionsSettings

GitHub Actions settings for the repository (Settings > Actions). Each field maps to one field of the Actions REST API.

Field Type Required Default Description
inherit boolean No - Set to false to drop every inherited actions setting, then apply this layer's own.
enabled boolean No - Whether GitHub Actions is enabled for the repository.
allowedActions all | local_only | selected No - Which actions and reusable workflows may run.
shaPinningRequired boolean No - Require actions to be referenced by full commit SHA.
githubOwnedAllowed boolean No - Allow actions created by GitHub when allowedActions is selected.
verifiedAllowed boolean No - Allow actions from Marketplace verified creators when allowedActions is selected.
patternsAllowed string[] | arrayMergeDirective No - Action patterns to allow when allowedActions is selected, such as docker/login-action@*.
defaultWorkflowPermissions read | write No - Default permissions of the GITHUB_TOKEN in workflows.
canApprovePullRequestReviews boolean No - Let workflows create and approve pull requests.
forkPrApprovalPolicy first_time_contributors_new_to_github | first_time_contributors | all_external_contributors No - Which contributors need approval before workflows run on their fork pull requests.
artifactAndLogRetentionDays integer No - Days to keep workflow artifacts and logs.
cacheRetentionDays integer No - Days to keep unused Actions caches.
cacheSizeGb integer No - Maximum Actions cache size in gigabytes.
  • inherit — Not valid at root level. Default: true
  • enabled — Maps to enabled of PUT actions/permissions. With false, allowedActions, shaPinningRequired and the selected-actions fields are not allowed in the same layer.
  • allowedActions — Maps to allowed_actions of PUT actions/permissions. The selected-actions fields apply only when this is selected.
  • shaPinningRequired — Maps to sha_pinning_required of PUT actions/permissions.
  • githubOwnedAllowed — Maps to github_owned_allowed of PUT actions/permissions/selected-actions.
  • verifiedAllowed — Maps to verified_allowed of PUT actions/permissions/selected-actions.
  • patternsAllowed — Maps to patterns_allowed of PUT actions/permissions/selected-actions. A pattern starting with ! blocks the action. Compared as a set. A plain list replaces the inherited patterns; use $arrayMerge to add to them.
  • defaultWorkflowPermissions — Maps to default_workflow_permissions of PUT actions/permissions/workflow.
  • canApprovePullRequestReviews — Maps to can_approve_pull_request_reviews of PUT actions/permissions/workflow, which covers creating pull requests as well as approving them.
  • forkPrApprovalPolicy — Maps to approval_policy of PUT actions/permissions/fork-pr-contributor-approval.
  • artifactAndLogRetentionDays — Maps to days of PUT actions/permissions/artifact-and-log-retention. The upper bound depends on visibility and plan, and GitHub enforces it.
  • cacheRetentionDays — Maps to max_cache_retention_days of PUT actions/cache/retention-limit. Needs a paid plan or a payment method on file.
  • cacheSizeGb — Maps to max_cache_size_gb of PUT actions/cache/storage-limit. Needs a paid plan or a payment method on file.

rootSettings

Global repository settings including GitHub Rulesets and repository features. inherit is not valid at root level.

Field Type Required Default Description
rulesets object of false | ruleset No - Map of ruleset names to configurations.
repo githubRepoSettings No - GitHub repository settings (features, merge options, security).
labels object of false | label No - Map of label names to configurations.
codeScanning codeScanningSettings No - GitHub code scanning default setup configuration.
actions actionsSettings No - GitHub Actions settings (Settings > Actions).
variables object of false | string No - Map of GitHub Actions variable names to values.
secrets object of false | secretConfig No - Map of GitHub Actions secret names to SecretConfig.
collaborators object No - Direct collaborators for personal (user-owned) repos.
environments object of false | rootEnvironmentConfig No - GitHub deployment environments keyed by name.
deleteOrphaned boolean No false When true, every ruleset and label in the repo that is not in the config is deleted, including ones created outside xfg.
  • rulesets — Set a ruleset to false to disable it.
  • labels — Set a label to false to disable it.
  • variables — Set a variable to false to disable it. Use deleteOrphaned to remove variables not in config.
  • secrets — Set a secret to false to disable it. Use deleteOrphaned to remove secrets not in config. Only synced by 'xfg secrets sync', never by 'xfg sync'.
  • collaborators — Org repos are skipped with a warning.
  • environments — Set an environment to false to disable it. Environments on GitHub that are not listed are kept unless deleteOrphaned is true. GitHub repos only; private repos need a paid plan.
  • deleteOrphaned — Default: false

See Secrets and GitHub Variables for scoping rules and the inherit / deleteOrphaned interaction.

repoSettings

Repository settings including GitHub Rulesets and repository features

Field Type Required Default Description
rulesets object of false | ruleset No - Map of ruleset names to configurations.
repo false | githubRepoSettings No - GitHub repository settings (features, merge options, security).
labels object of false | label No - Map of label names to configurations.
codeScanning false | codeScanningSettings No - GitHub code scanning default setup configuration.
actions false | actionsSettings No - GitHub Actions settings (Settings > Actions).
variables object of false | string No - Map of GitHub Actions variable names to values.
secrets object of false | secretConfig No - Map of GitHub Actions secret names to SecretConfig.
collaborators object No - Direct collaborators for personal (user-owned) repos.
environments object of false | environmentConfig No - GitHub deployment environments keyed by name, merged over inherited ones.
deleteOrphaned boolean No false When true, every ruleset and label in the repo that is not in the config is deleted, including ones created outside xfg.
  • rulesets — Set a ruleset to false to opt out. Set inherit: false to skip all inherited rulesets.
  • repo — Set to false at per-repo level to opt out of inherited settings.
  • labels — Set a label to false to opt out. Set inherit: false to skip all inherited labels.
  • codeScanning — Set to false at per-repo level to opt out of inherited settings.
  • actions — Set to false at per-repo level to opt out of inherited settings.
  • variables — Set a variable to false to opt out. Set inherit: false to skip all inherited variables.
  • secrets — Set a secret to false to opt out. Set inherit: false to skip all inherited secrets. Only synced by 'xfg secrets sync', never by 'xfg sync'.
  • collaborators — A plain users list replaces the inherited users; use $arrayMerge: append to add to them. Set inherit: false to drop inherited users.
  • environments — Set an environment to false to opt out. Set inherit: false to skip all inherited environments. Environments on GitHub that are not listed are kept unless deleteOrphaned is true.
  • deleteOrphaned — Default: false

githubRepoSettings

GitHub repository settings for features, merge options, and security

Field Type Required Default Description
inherit boolean No - Set to false to drop every inherited repo setting, then apply this layer's own.
description string No - Repository description.
hasIssues boolean No - Enable or disable GitHub Issues.
hasProjects boolean No - Enable or disable GitHub Projects.
hasWiki boolean No - Enable or disable the repository wiki.
hasDiscussions boolean No - Enable or disable GitHub Discussions
isTemplate boolean No - Mark the repository as a template repository
allowForking boolean No - Allow forking of a private repository
visibility public | private | internal No - Repository visibility.
archived boolean No - Archive the repository.
allowSquashMerge boolean No - Allow squash-merging pull requests
allowMergeCommit boolean No - Allow merge commits for pull requests
allowRebaseMerge boolean No - Allow rebase-merging pull requests
allowAutoMerge boolean No - Allow auto-merge on pull requests
deleteBranchOnMerge boolean No - Automatically delete head branches after pull requests are merged
allowUpdateBranch boolean No - Show 'Update branch' button in pull requests
squashMergeCommitTitle PR_TITLE | COMMIT_OR_PR_TITLE No - Default title for squash merge commits
squashMergeCommitMessage PR_BODY | COMMIT_MESSAGES | BLANK No - Default message for squash merge commits
mergeCommitTitle PR_TITLE | MERGE_MESSAGE No - Default title for merge commits
mergeCommitMessage PR_BODY | PR_TITLE | BLANK No - Default message for merge commits
vulnerabilityAlerts boolean No - Enable or disable Dependabot vulnerability alerts
automatedSecurityFixes boolean No - Enable or disable Dependabot automated security fixes
secretScanning boolean No - Enable or disable secret scanning
secretScanningPushProtection boolean No - Enable or disable secret scanning push protection
privateVulnerabilityReporting boolean No - Enable or disable private vulnerability reporting
webCommitSignoffRequired boolean No - Require contributors to sign off on web-based commits
defaultBranch string No - The default branch for the repository
  • inherit — Not valid at root level. Default: true
  • description — Used when creating new repositories via lifecycle management (upstream/source fields).
  • hasIssues — Warning: Disabling may hide existing issues.
  • hasProjects — Warning: Disabling may hide existing projects.
  • hasWiki — Warning: Disabling may hide existing wiki content.
  • visibility — Warning: Changing visibility may expose or hide repository content.
  • archived — Warning: Archived repositories are read-only.

arrayMergeDirective

Merge directive for any array in a layered settings block or in prOptions. A plain array replaces the inherited one; a directive appends to it, prepends to it, replaces it, or merges items into it. Repeated strings and numbers are dropped after the merge. deploymentBranchPolicy.custom takes append, prepend and replace, not merge.

Field Type Required Default Description
$arrayMerge replace | append | prepend | merge Yes - How to combine with the inherited array: 'append' adds after, 'prepend' adds before, 'replace' replaces entirely, 'merge' deep-merges items matched by $matchBy, or by an auto-detected identity key (type, actorId, actor_id)
$values any[] Yes - Values to combine with the inherited array
$matchBy string No - Key to match items on with $arrayMerge 'merge'; every item in both arrays must have it, with unique values

ruleset

GitHub Ruleset configuration

Field Type Required Default Description
inherit boolean No - Set to false to drop this ruleset's inherited fields, then apply this layer's own.
target branch | tag No branch Target type: 'branch' for branch rules, 'tag' for tag rules.
enforcement active | disabled | evaluate No active Enforcement level: 'active' enforces rules, 'disabled' turns off rules, 'evaluate' evaluates rules without blocking (dry run).
bypassActors bypassActor[] | arrayMergeDirective No - Actors who can bypass this ruleset
conditions rulesetConditions No - Conditions for when this ruleset applies (which branches/tags to target)
rules rulesetRule[] | arrayMergeDirective No - Rules to enforce on matching refs
  • inherit — Not valid at root level. Default: true
  • target — Default: branch
  • enforcement — Default: active

bypassActor

Actor who can bypass ruleset restrictions

Field Type Required Default Description
actorId integer Yes - The ID of the actor (team ID, user ID, or integration ID)
actorType Team | User | Integration Yes - Type of actor: Team, User, or Integration (GitHub App)
bypassMode always | pull_request | exempt No - When the actor can bypass: 'always' for all operations, 'pull_request' for PR operations only, 'exempt' to skip rule evaluation entirely (no bypass audit entry is created)

rulesetConditions

Conditions for when the ruleset applies

Field Type Required Default Description
refName object No - Ref name patterns to include/exclude

rulesetRule

One of:

pullRequestRule

Require pull request before merging

Field Type Required Default Description
type pull_request Yes -
parameters object No -

requiredReviewer

Required reviewer configuration for specific file patterns

Field Type Required Default Description
filePatterns string[] | arrayMergeDirective Yes - File path patterns that require this reviewer
minimumApprovals integer Yes - Minimum number of approvals required from this reviewer
reviewer object Yes -

requiredStatusChecksRule

Require status checks to pass

Field Type Required Default Description
type required_status_checks Yes -
parameters object No -

requiredSignaturesRule

Require signed commits

Field Type Required Default Description
type required_signatures Yes -

requiredLinearHistoryRule

Require linear history (no merge commits)

Field Type Required Default Description
type required_linear_history Yes -

nonFastForwardRule

Prevent force pushes

Field Type Required Default Description
type non_fast_forward Yes -

creationRule

Restrict ref creation

Field Type Required Default Description
type creation Yes -

deletionRule

Restrict ref deletion

Field Type Required Default Description
type deletion Yes -

updateRule

Restrict updates to refs

Field Type Required Default Description
type update Yes -
parameters object No -

requiredDeploymentsRule

Require deployments to succeed

Field Type Required Default Description
type required_deployments Yes -
parameters object No -

codeScanningRule

Require code scanning results

Field Type Required Default Description
type code_scanning Yes -
parameters object No -

codeQualityRule

Require code quality checks

Field Type Required Default Description
type code_quality Yes -
parameters object No -

workflowsRule

Require specific workflows to pass

Field Type Required Default Description
type workflows Yes -
parameters object No -

patternRule

Pattern-based rules for commit messages, author emails, etc.

Field Type Required Default Description
type commit_author_email_pattern | commit_message_pattern | committer_email_pattern | branch_name_pattern | tag_name_pattern Yes - Pattern rule type
parameters object Yes -

filePathRestrictionRule

Restrict changes to specific file paths

Field Type Required Default Description
type file_path_restriction Yes -
parameters object No -

fileExtensionRestrictionRule

Restrict changes to files with specific extensions

Field Type Required Default Description
type file_extension_restriction Yes -
parameters object No -

maxFilePathLengthRule

Restrict maximum file path length

Field Type Required Default Description
type max_file_path_length Yes -
parameters object No -

maxFileSizeRule

Restrict maximum file size

Field Type Required Default Description
type max_file_size Yes -
parameters object No -

label

GitHub label configuration

Field Type Required Default Description
inherit boolean No - Set to false to drop this label's inherited fields, then apply this layer's own.
color string Yes - Hex color code (with or without #).
description string No - Label description (max 100 characters)
new_name string No - Rename this label.
  • inherit — Not valid at root level. Default: true
  • color — Example: 'd73a4a' or '#d73a4a'
  • new_name — Maps to GitHub API's new_name field.

secretConfig

Secret configuration mapping to an environment variable source

Field Type Required Default Description
env string Yes - Name of the environment variable containing the secret value

rootEnvironmentConfig

A GitHub deployment environment

Field Type Required Default Description
deploymentBranchPolicy deploymentBranchPolicy No - Which refs can deploy.
secrets object of false | secretConfig No - Environment secrets keyed by name.
  • deploymentBranchPolicy — Omit to let any branch deploy.
  • secrets — Only synced by 'xfg secrets sync', never by 'xfg sync'. Set a secret to false to opt out.

environmentConfig

A GitHub deployment environment, merged over the inherited one

Field Type Required Default Description
inherit boolean No - Set to false to drop this environment's inherited policy and secrets, then apply this layer's own.
deploymentBranchPolicy false | deploymentBranchPolicy No - Which refs can deploy.
secrets object of false | secretConfig No - Environment secrets keyed by name.
  • inherit — Not valid at root level. Default: true
  • deploymentBranchPolicy — Fields merge with the inherited policy; set inherit: false in it to drop the inherited fields, or false to clear the policy.
  • secrets — Only synced by 'xfg secrets sync', never by 'xfg sync'. Set a secret to false to opt out.

deploymentBranchPolicy

Which refs can deploy. Layers merge field by field, and the merged policy must have exactly one of protectedBranches: true or custom; to switch between them, set inherit: false in the layer that changes it. Omit the policy to let any branch deploy.

Field Type Required Default Description
inherit boolean No - Set to false to drop the inherited policy, then apply this layer's own.
protectedBranches true No - Only branches with branch protection rules can deploy
custom deploymentBranchPattern[] | arrayMergeDirective No - Only refs matching these patterns can deploy.
deleteOrphaned boolean No false Delete patterns on GitHub that are not in the merged custom list.
  • inherit — Not valid at root level. Default: true
  • custom — A plain list replaces the inherited patterns; use $arrayMerge: append to add to them. A pattern is identified by type and name together, so $arrayMerge: merge is not accepted. Patterns on GitHub that are not listed here are left in place with a warning unless deleteOrphaned is true.
  • deleteOrphaned — Inherited like other fields; only valid with custom. Default: false

deploymentBranchPattern

A branch or tag name pattern allowed to deploy

Field Type Required Default Description
type branch | tag Yes - Whether the pattern matches branches or tags
name string Yes - fnmatch-style name pattern, e.g. main, release/, v..

See Environments.

Validation

The JSON Schema describes property types and enum values for editors. The schema root has no required list, so editors don't flag a missing id or repos. xfg's own validator runs when a config loads and enforces:

  • Required fields (id, repos)
  • 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 names or @path file references)

Config Requirements

The xfg sync command accepts configs with files, settings, or both. A config needs files at root or in a group or conditional group, or settings with at least one entry at root, repo, group, or conditional group level.

Settings that hold only secrets don't count, because xfg sync never processes secrets (use xfg secrets sync). prOptions alone at root or in groups is not enough, while a conditional group that sets only prOptions passes this check.