PR Options¶
Configure how PRs are handled after creation.
PR Options Fields¶
| Field | Description | Default |
|---|---|---|
merge |
Merge mode: manual (leave open), auto (merge when checks pass), force, direct |
auto |
mergeStrategy |
How to merge: merge, squash, rebase |
squash |
deleteBranch |
Delete source branch after merge | true |
bypassReason |
Reason for bypassing policies (Azure DevOps only, used by force). If unset: Automated config sync via xfg |
- |
labels |
Labels to apply to created PRs (GitHub only) | - |
branch |
Branch name for sync PRs. Per-repo overrides group, group overrides global. CLI --branch flag overrides all. |
- |
ai |
AI-generated commit messages and PR descriptions. true or an options object |
- |
Merge Modes¶
| Mode | GitHub Behavior | Azure DevOps Behavior | GitLab Behavior |
|---|---|---|---|
manual |
Leave PR open for review | Leave PR open for review | Leave MR open for review |
auto |
Enable auto-merge (requires repo setup, default) | Enable auto-complete (default) | Merge when pipeline succeeds (default) |
force |
Merge with --admin (bypass checks) |
Bypass policies with --bypass-policy |
Merge immediately |
direct |
Push directly to default branch (no PR) | Push directly to default branch (no PR) | Push directly to default branch (no MR) |
Global vs Per-Repo Options¶
Set global defaults, then override per-repo as needed:
id: pr-options
files:
.prettierrc.json:
content:
semi: false
prOptions:
merge: auto
mergeStrategy: squash
deleteBranch: true
repos:
# Uses global defaults
- git: git@github.com:org/frontend.git
# Override to manual
- git: git@github.com:org/needs-review.git
prOptions:
merge: manual
# Override to force merge
- git: git@github.com:org/internal-tool.git
prOptions:
merge: force
PR Labels¶
Apply labels to PRs automatically:
id: pr-options
files:
.prettierrc.json:
content: { semi: false }
prOptions:
labels: ["config-sync", "automated"]
repos:
# Uses global labels
- git: git@github.com:org/frontend.git
# Override with repo-specific labels (replaces global)
- git: git@github.com:org/critical.git
prOptions:
labels: ["critical-config", "urgent"]
# Add to the global labels
- git: git@github.com:org/extra.git
prOptions:
labels:
$arrayMerge: append
$values: ["extra"]
# Clear labels for this repo
- git: git@github.com:org/no-labels.git
prOptions:
labels: []
Note: Labels must already exist on the target repository. If a label doesn't exist, the PR creation will fail. GitHub only.
prOptions set in a group or repo merges field by field with the options it inherits, and so does an ai object inside it (see AI Messages). Set inherit: false inside prOptions to drop everything inherited, ai included, and use only that layer's own options.
Set inherit inside ai to drop only the inherited ai fields. inherit is not allowed in the root prOptions or the root ai.
PR Branch Name¶
Set a custom branch name for sync PRs:
id: pr-options
files:
.prettierrc.json:
content: { semi: false }
# Global branch name
prOptions:
branch: chore/sync-config
repos:
# Uses global branch name
- git: git@github.com:org/frontend.git
# Per-repo override
- git: git@github.com:org/special.git
prOptions:
branch: chore/sync-repo-specific
When branch is not set, the branch is chore/sync-config. If the config syncs exactly one file name across all repos, the branch is named after that file instead (.prettierrc.json gives chore/sync-prettierrc). The CLI --branch flag overrides all config values.
CLI Override¶
CLI flags take highest priority:
# Disable auto-merge, leave PRs open for review
xfg sync --config ./config.yaml --merge manual
# Force merge all PRs (useful for urgent updates)
xfg sync --config ./config.yaml --merge force
# Push directly to default branch without creating PRs
xfg sync --config ./config.yaml --merge direct
Direct Push Mode¶
The direct mode pushes changes directly to the default branch without creating a PR. This is useful for:
- Repos without branch protection
- Internal tools where PR review isn't required
- Quick config updates where you have direct push permissions
id: pr-options
files:
.prettierrc.json:
content: { semi: false }
prOptions:
merge: direct
repos:
- git: git@github.com:org/internal-tool.git
Note: If the target branch has branch protection enabled, the push will fail with a helpful error message suggesting to use merge: force instead.
GitHub Auto-Merge Note¶
The auto mode requires auto-merge to be enabled in the repository settings. If not enabled, the tool will warn and leave the PR open for manual review.
Enable it with:
Priority Order¶
- CLI flags (highest)
- Per-repo
prOptions - Conditional group
prOptions(applied in array order) - Group
prOptions(applied in order, later groups override earlier ones) - Global
prOptions - Built-in defaults (lowest)