Merge Strategies¶
Control how arrays and text lines merge when combining base content with per-repo overlays.
Strategies¶
| Strategy | Behavior |
|---|---|
replace |
Overlay completely replaces base |
append |
Overlay items added after base items |
prepend |
Overlay items added before base items |
merge |
Deep-merges array items matched by identity key (type, actorId, actor_id); unmatched items appended |
File-Level Strategy¶
Set a default strategy for a file using mergeStrategy:
id: merge-strategies
files:
.eslintrc.json:
mergeStrategy: append # extends arrays will append
content:
extends: ["@company/base"]
repos:
- git: git@github.com:org/frontend.git
files:
.eslintrc.json:
content:
extends: ["plugin:react/recommended"]
Result: ["@company/base", "plugin:react/recommended"]
File-Level vs Inline Control¶
- File-level
mergeStrategy: Sets the default for ALL arrays in that file - Inline
$arrayMerge: Overrides the strategy for specific arrays within content
Use file-level when all arrays in a file should merge the same way. Use inline $arrayMerge when you need per-array control, especially in per-repo overlays.
Inline Array Merge Directive¶
For per-field control, use $arrayMerge and $values directives on individual array fields:
id: merge-strategies
files:
config.json:
content:
features: ["core", "monitoring"]
repos:
- git: git@github.com:org/repo.git
files:
config.json:
content:
features:
$arrayMerge: append
$values: ["custom-feature"]
Result: ["core", "monitoring", "custom-feature"]
Per-Array Control¶
Each array field gets its own directive, so sibling arrays can use different strategies:
id: merge-strategies
files:
config.json:
content:
features: ["core", "monitoring"]
tags: ["production"]
repos:
- git: git@github.com:org/repo.git
files:
config.json:
content:
features:
$arrayMerge: append
$values: ["custom-feature"]
tags:
$arrayMerge: prepend
$values: ["priority"]
Result:
features:["core", "monitoring", "custom-feature"]tags:["priority", "production"]
All Strategies¶
# append — add after base items
features:
$arrayMerge: append
$values: ["new-item"]
# Base ["a", "b"] + overlay ["c"] = ["a", "b", "c"]
# prepend — add before base items
features:
$arrayMerge: prepend
$values: ["new-item"]
# Base ["a", "b"] + overlay ["c"] = ["c", "a", "b"]
# replace — completely replace base (default behavior)
features:
$arrayMerge: replace
$values: ["new-item"]
# Base ["a", "b"] + overlay ["c"] = ["c"]
# merge — deep-merge items matched by identity key
rules:
$arrayMerge: merge
$values:
- type: pull_request
parameters:
requiredApprovingReviewCount: 2
# Base [{type: "pull_request", parameters: {requiredApprovingReviewCount: 1}}]
# Result: [{type: "pull_request", parameters: {requiredApprovingReviewCount: 2}}]
Directives are stripped
$arrayMerge, $values and $matchBy are internal directives and do not appear in the final output.
A directive is an object made only of directive keys. It must be the value of a key, needs one of the four strategies above, and needs a $values array. Where the base has no array under that key:
- With no base value, or a scalar or
nullone, the directive resolves to its$values. This includes a directive in root content that nothing overlays. - Over a base object, the directive is dropped and the base object is kept unchanged.
A directive as an array item or as the whole content is a config error, as is one with an unknown strategy or no $values array. The error names the file or ruleset and the path to the directive. An object that mixes directive keys with other keys is not a directive: with no base array to merge into, xfg drops its directive keys and keeps the rest.
Merge by Key¶
The merge strategy matches array items by an identity key and deep-merges matched pairs. This is useful when multiple conditional groups need to modify properties of the same item rather than duplicating it.
How it works:
- xfg uses the
$matchBykey if the directive sets one; otherwise it auto-detects the identity key by checking candidates in order:type,actorId,actor_id - The first candidate key present in every item of both arrays wins
- For each overlay item: if a base item shares the same key value, the two are deep-merged; otherwise the overlay item is appended
- Unmatched base items are preserved in their original position
- Nested
$arrayMergedirectives inside matched items are honored (deep-merge recurses)
Matching uses a single key, so two bypass actors with the same actorId but different actorType are treated as one. Use append to keep both.
When no match key is found (e.g. primitive arrays or objects without type/actorId/actor_id), the strategy falls back to append behavior.
# Example: merging required_status_checks across conditional groups
settings:
rulesets:
pr-rules:
rules:
- type: pull_request
parameters:
requiredApprovingReviewCount: 1
- type: required_status_checks
parameters:
requiredStatusChecks:
- context: "ci / build"
conditionalGroups:
- when:
allOf: [has-mergify]
settings:
rulesets:
pr-rules:
rules:
$arrayMerge: merge
$values:
- type: required_status_checks
parameters:
requiredStatusChecks:
$arrayMerge: append
$values:
- context: "mergify / queue"
Result for repos with has-mergify: the required_status_checks rule has both ci / build and mergify / queue checks — no duplication of the rule itself, and the nested $arrayMerge: append adds the check inside the matched item.
Match by a Chosen Key¶
For lists keyed by anything other than type, actorId or actor_id, name the key with $matchBy. Mergify's queue_rules, for example, are keyed by name:
files:
.mergify.yml:
content:
queue_rules:
- name: default
merge_conditions:
- check-success = lint
- name: hotfix
merge_conditions:
- label = hotfix
groups:
ci-repo:
files:
.mergify.yml:
content:
queue_rules:
$arrayMerge: merge
$matchBy: name
$values:
- name: default
merge_conditions:
$arrayMerge: append
$values:
- check-success = repo-summary / Check Results
Result for repos in ci-repo: the default rule's merge_conditions are check-success = lint and check-success = repo-summary / Check Results, and the hotfix rule is unchanged.
Items with the same $matchBy value are deep-merged, so nested directives apply. Overlay items with no match are appended. $matchBy works everywhere $arrayMerge works, in file content and in settings.
$matchBy fails closed. Each of these is a config error that names the file or ruleset and the path to the array:
$matchBywith any strategy other than$arrayMerge: merge- An item in either array without the
$matchBykey - A
$matchByvalue that is not a string, number, boolean or null - Two items in the same array with the same
$matchByvalue
Without $matchBy, merge auto-detects type, actorId or actor_id. name is deliberately not auto-detected: many lists have name fields (workflow steps, for example), and matching them automatically would silently change existing merges.
Text File Merge Strategies¶
For text files with lines array content, merge strategies work the same way:
id: merge-strategies
files:
.gitignore:
mergeStrategy: append
content:
- "node_modules/"
- "dist/"
repos:
- git: git@github.com:org/repo.git
files:
.gitignore:
content:
- "coverage/" # Appended to base
Result:
For lines arrays, merge behaves like append: lines have no identity key to match on, so overlay lines are added after the base lines.
Note
String content (not lines array) always uses replace strategy - the entire string is replaced.
Settings Array Merge¶
Settings blocks and prOptions share one merge model, through root, groups, conditional groups and the repo:
- Objects merge field by field. A field a layer leaves out is inherited.
- A plain array replaces the inherited array.
- A
$arrayMergedirective combines with it:append,prepend,replaceormerge, with$values(and$matchByformerge). It is the same syntax as in file content, and it works on every array in the list below. inherit: falsestarts a block fresh. Inside a block, it drops everything that block would inherit, then the layer's own fields apply. It works inrepo,actions,codeScanning,deploymentBranchPolicy,prOptionsandprOptions.ai, and, as before, in rulesets, labels, environments, collaborators, variables and secrets. It is not allowed at root, where there is nothing to inherit.inherit: falseinside one ruleset, label or environment drops only that entry's inherited fields. In therulesetsorlabelsmap, a same-named entry then replaces the inherited one, so restate it in full.falseopts out. Setting a block (or a named entry) tofalseremoves it.deleteOrphanedis an ordinary field. The innermost layer wins, and where it deletes things on GitHub it works on the merged result, so an appended item is kept, not deleted.- Repeated items are dropped from the merged array, first one wins (usernames are compared ignoring case). Only strings and numbers are compared; objects are never dropped.
The arrays that take a directive:
| Block | Arrays |
|---|---|
| Rulesets | bypassActors, rules, conditions.refName.include, conditions.refName.exclude |
| Rule parameters | allowedMergeMethods, requiredReviewers (and its filePatterns), requiredStatusChecks, requiredDeploymentEnvironments, codeScanningTools, workflows, restrictedFilePaths, restrictedFileExtensions |
| Code scanning | languages |
| Actions | patternsAllowed |
| Collaborators | users |
| Environments | deploymentBranchPolicy.custom |
| PR options | labels |
custom does not take merge
A deployment branch pattern is identified by its type and name together, and no single $matchBy key covers both: $matchBy: name would fold a branch pattern and a tag pattern with the same name into one, and with deleteOrphaned: true xfg would then delete one of them on GitHub. xfg rejects $arrayMerge: merge on custom, with or without $matchBy; use append, prepend or replace.
Appending Bypass Actors¶
id: merge-strategies
# Root — shared across all repos
settings:
rulesets:
pr-rules:
bypassActors:
- actorId: 2740 # Renovate
actorType: Integration
bypassMode: always
repos:
# Adds a repo-specific actor without duplicating Renovate
- git: git@github.com:org/repo.git
settings:
rulesets:
pr-rules:
bypassActors:
$arrayMerge: append
$values:
- actorId: 2719952 # repo-specific bot
actorType: Integration
bypassMode: always
Result: bypassActors contains both Renovate (actorId 2740) and the repo-specific bot (actorId 2719952).
Appending Rules via Conditional Groups¶
settings:
rulesets:
pr-rules:
rules:
- type: pull_request
parameters:
requiredApprovingReviewCount: 1
groups:
github-ci: {}
conditionalGroups:
- when:
allOf: [github-ci]
settings:
rulesets:
pr-rules:
rules:
$arrayMerge: append
$values:
- type: required_status_checks
parameters:
requiredStatusChecks:
- context: "summary / Check Results"
Repos with the github-ci group get both the pull_request rule and the required_status_checks rule. Repos without github-ci only get the pull_request rule.
Replacing or Adding to a Plain List¶
A plain list replaces the inherited one. A directive adds to it:
id: merge-strategies
settings:
actions:
allowedActions: selected
patternsAllowed:
- actions/*
repos:
# Replaces the inherited patterns
- git: git@github.com:org/strict.git
settings:
actions:
patternsAllowed:
- actions/checkout@*
# Adds to the inherited patterns
- git: git@github.com:org/docker.git
settings:
actions:
patternsAllowed:
$arrayMerge: append
$values:
- docker/login-action@*
Starting a Block Fresh¶
inherit: false drops everything the block would inherit, so a layer can state a block from scratch:
id: merge-strategies
settings:
codeScanning:
state: configured
languages: [go, python]
repos:
# Inherits state and languages
- git: git@github.com:org/api.git
# Drops the inherited languages, so GitHub auto-detects them
- git: git@github.com:org/web.git
settings:
codeScanning:
inherit: false
state: configured
Same syntax as file content
The $arrayMerge directive uses the same $arrayMerge + $values syntax in settings as in file content (see Inline Array Merge Directive above). Strategies: append, prepend, replace, merge. merge accepts $matchBy here too.
Example: Different Strategies per File¶
id: merge-strategies
files:
eslint.config.json:
mergeStrategy: append # Extends will append
content:
extends: ["@company/base"]
tsconfig.json:
mergeStrategy: replace # Lib will replace entirely
content:
compilerOptions:
lib: ["ES2022"]
repos:
- git: git@github.com:org/frontend.git
files:
eslint.config.json:
content:
extends: ["plugin:react/recommended"]
# Results in extends: ["@company/base", "plugin:react/recommended"]
tsconfig.json:
content:
compilerOptions:
lib: ["ES2022", "DOM"]
# Results in lib: ["ES2022", "DOM"] (replaced)