Skip to content

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:

gh repo edit org/repo --enable-auto-merge

Priority Order

  1. CLI flags (highest)
  2. Per-repo prOptions
  3. Conditional group prOptions (applied in array order)
  4. Group prOptions (applied in order, later groups override earlier ones)
  5. Global prOptions
  6. Built-in defaults (lowest)