Config Schema Reference¶
The full JSON Schema for xfg configuration files is available at:
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: falsesettings— 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: replacecreateOnly— Useful for files like .trivyignore or .prettierignore where you want to provide defaults but let repos customize. Default: falseheader— 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: falsevars— 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 formatsfiles— 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: truemerge— Default: automergeStrategy— Default: squashdeleteBranch— Default: truebypassReason— Default: Automated config sync via xfglabels— 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: trueprovider— 'openai' uses any OpenAI-compatible Chat Completions API (OpenAI, Ollama, Azure OpenAI, LiteLLM). Default: anthropicmodel— Default for anthropic: claude-haiku-4-5. Required for openai.baseUrl—http://localhost:11434/v1for 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_KEYheadersEnv— 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: 20000fallback— 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: anthropicmodel— Default for anthropic: claude-haiku-4-5. Required for openai.baseUrl—http://localhost:11434/v1for 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_KEYheadersEnv— 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: falseheader— 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: truestate— 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: trueenabled— 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: truedescription— 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: truetarget— Default: branchenforcement— 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:
pullRequestRulerequiredStatusChecksRulerequiredSignaturesRulerequiredLinearHistoryRulenonFastForwardRulecreationRuledeletionRuleupdateRulerequiredDeploymentsRulecodeScanningRulecodeQualityRuleworkflowsRulepatternRulefilePathRestrictionRulefileExtensionRestrictionRulemaxFilePathLengthRulemaxFileSizeRule
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: truecolor— 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: truedeploymentBranchPolicy— 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: truecustom— 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
@pathfile 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.