feat(custom_properties): support include/exclude to preserve unmanaged property values

[jordonpeterson]

Lets a custom_properties config declare the properties it manages and leave
properties owned by other automation untouched, instead of clearing every property
it does not list.

Closes #986 — implements the include/exclude shape requested there, mirroring
the Labels plugin as the issue suggests.

What

custom_properties:
  include:
    - name: ruleset-tier
      value: strict
  exclude:
    # Regexes, matched against the property name
    - name: ^team-

To manage only what you declare and leave every other property alone, exclude
everything with .*:

custom_properties:
  include:
    - name: ruleset-tier
      value: strict
  exclude:
    - name: .*

The existing plain-array shape is unchanged.

Why

Custom properties cannot be deleted through the API, so Diffable's removal path
sets value: null. Any property present on a repository but absent from config was
therefore cleared on every sync — including values written by other automation. In
effect safe-settings claimed exclusive ownership of the entire custom-properties
surface of any repo with a custom_properties section, with no way to opt out short
of dropping the section altogether. That is exactly the case #986 describes:
org-wide properties should be enforced while per-repo ones are left alone.

Behavior

• A property matching an exclude regex is never cleared.
• A property in include is created/updated as before, even if it also matches an
  exclude pattern. include wins.
• exclude on its own still means safe-settings manages this repo's properties —
  everything not matching a pattern is cleared. To manage nothing, omit the section.

Config mistakes fail closed rather than clearing values — see the design notes below.

Changes

• lib/plugins/custom_properties.js — config-shape detection, exclude-pattern
  compilation, exclude check in remove()
• test/unit/lib/plugins/custom_properties.test.js — 28 new tests
• README.md — "Preserving custom properties that safe-settings does not
  manage", alongside the existing include/exclude notes for collaborators, teams
  and labels
• docs/sample-settings/settings.yml — worked example, linking to the README for
  the semantics
• schema/{repos,settings,suborgs}.json — accept both shapes; require the object
  form to carry include, exclude, or both
• schema/dereferenced/*.json — 6 of the 10 changed files are these generated
  schemas. Their custom_properties blocks are verified byte-equal to
  npm run build:schema output. They are spliced in rather than committed wholesale
  because a full regeneration also pulls in unrelated repositories/teams/rulesets
  churn from the live GitHub API description, which drifts on main-enterprise
  independently of this change.

Testing

New behavior — test/unit/lib/plugins/custom_properties.test.js passes 33/33,
covering exclude protection, include-wins precedence, casing on both the API
response and the pattern, nop mode, degenerate configs, invalid regexes, and
malformed object configs.

Existing behavior is provably unchanged. Since this touches a path that nulls out
property values, the old behavior was verified directly rather than by inspection: a
15-scenario matrix (× apply and nop modes = 30 runs) was run against the plugin as it
exists on main-enterprise and against this branch, capturing API writes,
NopCommands, normalized entries, and recorded errors for each. The two transcripts
are byte-identical. The matrix uses only pre-change config shapes — plain arrays,
null, undefined — and covers update, create, no-op, clearing unmanaged properties,
the property_name key variant, mixed casing on both sides, nameless and non-object
entries, and multi-property syncs. 11 of the 30 runs perform API writes and 11 emit
NopCommands, so the comparison is exercising real output.

The schemas were checked the same way: every config shape that validated against the
schema on main-enterprise still validates here — empty array, {name,value},
{property_name,value}, multiple entries, name-only, and no custom_properties key.
Zero regressions.

npm run test:unit (what CI runs) passes 162 tests across 16 suites. standard is
clean on both changed files, and eslint reports the same 145 pre-existing problems
as the base commit — no new lint.

Verified against a real organization

The unit tests stub the GitHub client, so the plugin was also dry-run against a real
organization using ProbotOctokit in nop mode — real API, real response shapes, real
pagination — with the write endpoint replaced by a guard that throws if called, so no
modification was possible.

Setup: three custom properties defined on a scratch org and set on one repository.
safe-settings-managed is the property safe-settings declares; ext-deploy-status
and ext-cost-center stand in for values written by other automation.

plugin	config	properties it would clear
main-enterprise	legacy array	ext-cost-center, ext-deploy-status — 2 Delete commands
this branch	same legacy array	ext-cost-center, ext-deploy-status — 2 Delete commands (identical)
this branch	include + exclude: ^ext-	none — 0 Delete commands

The middle row is the backward-compatibility check: with a legacy config the plan this
branch produces is byte-identical to the plan the current plugin produces, against the
same live repository. The third row is the fix. All three runs recorded 0 write
attempts. The org was cleaned up afterwards.

Two things this surfaced that are worth flagging:

• @octokit/plugin-rest-endpoint-methods v17 renamed both endpoints this plugin
  calls — getCustomPropertiesValues and createOrUpdateCustomPropertiesValues are
  both undefined on the currently installed client, so find() throws against a real
  API regardless of this PR. That is issue 2.1.21: CustomProperties plugin still crashes — modifyProperty() calls renamed octokit methods #981 / PR Fix CustomProperties plugin calls renamed in @octokit/plugin-rest-endpoint-methods v17 #1032; the dry run shimmed the old
  names onto the new ones to get past it. Worth noting that Fix CustomProperties plugin calls renamed in @octokit/plugin-rest-endpoint-methods v17 #1032 is effectively a
  prerequisite for this feature working at runtime. The unit tests do not catch it
  because they stub the client methods by name.
• In nop mode the "Changes found" summary still lists excluded properties under
  deletions, because Diffable.sync() computes that summary from compareDeep
  before remove() runs. No Delete command is emitted and nothing is written — the
  listing is cosmetic, but a dry-run reader may find it confusing.

Design notes: why config errors fail closed, and where this diverges from Labels

The include/exclude vocabulary and the unanchored-regex matching follow
lib/plugins/labels.js. Two deliberate divergences, both because the cost of
misreading an exclude pattern here is cleared property values rather than a stray
label:

• Patterns are lowercased when compiled. Property names are lowercased before
  matching, so an uppercase pattern would otherwise be a valid regex that silently
  matches nothing and clears the properties it was written to protect.
• An invalid pattern fails closed. It is recorded as a per-repo config error and
  every property on that repo is treated as excluded, so a typo protects values
  rather than clearing them. This matters because these are regexes, not globs — the
  intuitive * is not a valid pattern, and under a fail-open reading it would clear
  every unmanaged property. Properties in include are still applied.

A malformed object config fails closed the same way. The object form requires
include, exclude, or both; the schemas reject anything else, but the plugin does
not rely on them — they are authoring aids, not a runtime gate, since nothing in
lib/ validates config against them. Without the runtime check
custom_properties: {} reached normalizeEntries and threw a TypeError out of the
constructor.

Errors are recorded rather than thrown throughout: child plugins are constructed
outside any try/catch in Settings.updateRepos, so throwing would reject the org-wide
Promise.all and abort the sync for every other repo. A bad config in one repo should
not take down the org's sync.

Happy to rebase if #1032 lands first — it touches the same plugin.

[Copilot]

Pull request overview

This PR extends the custom_properties plugin to support an { include, exclude } configuration shape, allowing safe-settings to manage only declared properties while preserving values owned by other automation via exclude regexes. It also updates schemas, docs, and unit tests to cover the new behavior while keeping the existing plain-array config shape unchanged.

Changes:

• Add { include, exclude } config-shape support to custom_properties, including exclude-regex compilation and delete short-circuiting.
• Update JSON schemas (and dereferenced copies) to accept both the legacy array shape and the new object shape.
• Document the ownership/clearing caveat and add unit tests for include/exclude behavior, casing, nop-mode, and invalid regex handling.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
lib/plugins/custom_properties.js	Implements include/exclude shape detection, exclude regex compilation, and protected remove behavior.
test/unit/lib/plugins/custom_properties.test.js	Adds unit tests validating new include/exclude behavior and regressions for the legacy array shape.
schema/repos.json	Updates repo override schema to accept both array and object forms for custom_properties.
schema/settings.json	Updates org-level schema to accept both array and object forms for custom_properties.
schema/suborgs.json	Updates suborg-level schema to accept both array and object forms for custom_properties.
schema/dereferenced/repos.json	Mirrors the schema change in the dereferenced repo schema.
schema/dereferenced/settings.json	Mirrors the schema change in the dereferenced settings schema.
schema/dereferenced/suborgs.json	Mirrors the schema change in the dereferenced suborg schema.
docs/sample-settings/settings.yml	Documents the new object form and the “clearing sets value to null” ownership caveat.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jordonpeterson]

Fixed — the object branch now requires at least one of the two keys:

"anyOf": [
  { "required": ["include"] },
  { "required": ["exclude"] }
]

Verified with ajv against the dereferenced schema: custom_properties: {} and { bogus: 1 } are now rejected, while the array form, { include }, { exclude } and { include, exclude } all still validate. Applied to all three source schemas and their dereferenced counterparts.

[jordonpeterson]

Fixed here too — same anyOf / required change as on schema/repos.json, so {} no longer validates.

[decyjphr]

@jordonpeterson please look at this feature already in the code in yadhav/fix-recent-issues branch.

That should meet your requirements.

[jordonpeterson]

Thanks @decyjphr — additive_plugins works great for what I need. I dry-ran it against a real org and it does exactly what I wanted: deletions suppressed, declared values still applied.

The one gap is that it's all-or-nothing per plugin, whereas #986 asks to exclude specific properties while still clearing others. This PR covers that case and is tested, but it's entirely up to you whether that configurability is worth carrying — happy for this to be closed if not.

Thanks!