Preserve selectively excluded custom property values

[decyjphr]

Why

Safe-settings currently clears undeclared custom property values unless additive_plugins suppresses all removals. This adapts #1036 so users can preserve selected properties owned by other automation while still clearing other undeclared values.

Approach

• Support custom_properties: { include, exclude } alongside legacy lists. Includes take precedence, including explicit null clears; exclusions use case-insensitive regexes without rewriting escapes or character classes.
• Fail closed on malformed objects, include values, or exclusion patterns: record per-repository errors, suppress clears, and retain safe non-null included writes.
• Merge mixed list/object layers after disable_plugins stripping, preserving org/suborg/repo precedence, aliases, complete multi-value overrides, additive mode, and null resets.
• Exclude protected values before comparison so dry-run summaries, commands, and change signals match apply behavior. Preserve existing raw GET/PATCH routes and avoid changes to shared Diffable/MergeDeep behavior.
• Document the configuration, regenerate all three schemas through npm run build:schema, and add regression coverage plus maintained smoke phase 20.

Source audit

Adapted source commit 47c5a4190fa31562a8f7e2a6210182d528952d50 from #1036 into ed993857c8e4dca64cb75405cad3238a7dab68b2, based directly on target commit 8135a2e87ad1de32adf2d5b5f371ca002ffb0192. No unrelated source ancestry was imported. The #1032 API prerequisite was already covered on the target and was not reapplied.

Validation

Using nvm Node 22.12.0 / npm 10.9.0:

• npm run test:unit -- --runInBand --silent: 673 passed, 12 skipped; focused property/settings/schema tests: 218 passed.
• Installed Octokit exercised through local HTTP for pagination, PATCH serialization, NOP payloads, and fail-closed behavior.
• Repeated npm run build:schema produced identical output; no generated changes outside custom-property definitions and sections.
• Live smoke phases 1, 4, 5, custom-property phase 12a-d, and 20, plus standard setup/teardown: 76 passed, 0 failed, with every selected phase completed and no fatal errors. A session-only catalog filter omitted only the unrelated phase-12 roles/rulesets entries; selected assertions were unchanged.
• Independent cleanup inventory exactly matched preflight: owned fixtures removed, original refs/property definitions/admin policies preserved, and server stopped.

Baseline limitations: the unchanged integration suite fails before executing tests at the Probot 14 ESM/Jest 29 boundary. Fifteen existing lint errors in settings/smoke code were reproduced on the base; changed plugin and regression tests lint cleanly.

[Copilot]

Copilot review overview

🟡 Changes recommended

The schemas reject documented null resets, array values can cause redundant writes, and smoke cleanup can fail for automatically deleted branches.

Review effort: Balanced
Findings: 5

Open (5)

• Compare array property values by content before PATCHing · New
• Allow null custom_properties resets for repository configurations · New
• Allow null custom_properties resets for org configurations · New
• Allow null custom_properties resets for suborg configurations · New
• Use idempotent branch deletion for merged PR heads · New

What changed in this PR

Adds selective ownership of repository custom properties while preserving legacy behavior and fail-closed handling.

Changes:

• Adds include/exclude configuration and layered merging.
• Updates schemas and documentation.
• Adds unit and smoke-test coverage.

File	Description
lib/​plugins/​custom_properties.js	Implements selective property ownership.
lib/​settings.js	Merges layered custom-property configuration.
README.md	Documents ownership semantics.
docs/​sample-settings/​settings.yml	Adds configuration example.
smoke-test.js	Adds phase 20 integration coverage.
schema/​settings.json	Extends organization schema.
schema/​repos.json	Extends repository schema.
schema/​suborgs.json	Extends suborganization schema.
schema/​dereferenced/​settings.json	Regenerates organization schema.
schema/​dereferenced/​repos.json	Regenerates repository schema.
schema/​dereferenced/​suborgs.json	Regenerates suborganization schema.
test/​unit/​schema.test.js	Tests schema validation.
test/​unit/​lib/​settings-custom-properties.test.js	Tests layered merging.
test/​unit/​lib/​plugins/​custom_properties.test.js	Tests plugin ownership behavior.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.