Yadhav/fix recent issues

[decyjphr]

Background

Starting with the version 2.1.18 that seemed to be most stable, I've been testing and fixing minor bugs and adding a few critical features and enhancements:

This pull request introduces several major improvements and features to safe-settings, including enhanced plugin control, suborg re-evaluation logic, expanded documentation, and updated permissions for custom roles. The most important changes are grouped and summarized below.

---

Plugin Control Enhancements

• Disabling plugins with disable_plugins: Adds support for disabling safe-settings plugins at any config layer (deployment, org, suborg, repo) using a new disable_plugins key. Includes a detailed strip matrix, cascade rules, and limitations. Documentation and sample settings files have been updated with usage examples. [1]], [2]], [3]], [4]], [5]])
• Additive plugins with additive_plugins: Introduces the additive_plugins key at the org level, allowing selected Diffable plugins to only add or update entries, never remove them. This enables merging external changes with policy. Documentation and samples are provided. [1]], [2]])

Suborg Re-evaluation Logic

• Automatic suborg re-evaluation after repo-level changes: When a repo-level change might affect suborg membership (e.g., teams, properties, name), safe-settings now re-evaluates suborgs and re-applies settings if a new suborg matches. Includes loop prevention and performance optimizations. ([README.mdR181-R201])

Permissions and Integration Updates

• Custom roles permissions for GitHub App: Updates app.yml to request the necessary permissions for managing custom organization and repository roles, supporting new features in GitHub Enterprise Cloud. ([app.ymlR116-R123])
• Webhook event deduplication and improved sync logic: Refactors the main sync functions in index.js to deduplicate repo/suborg changes and streamline sync operations for selected repos and suborgs. [1]], [2]], [3]])

Documentation Improvements

• Smoke test documentation: Adds comprehensive instructions and explanations for running the end-to-end smoke test, including prerequisites, configuration, usage, and test phases. ([README.mdR717-R811])
• External group linking for teams: Documents the new external_group property for teams, describing how to link GitHub teams to external IdP groups via API. ([docs/github-settings/4. teams.mdR51-R63])

Other

• Minor cleanup in app.yml for formatting. ([app.ymlL28])

---

These changes significantly improve the flexibility, safety, and observability of safe-settings, especially for large organizations with complex policies.

[Copilot]

Pull request overview

This PR significantly expands safe-settings capabilities by adding enterprise app-installation management, a “reverse” settings generator, and multiple plugin-behavior enhancements (disable/additive plugins, teams external group linking, ruleset name→id aliasing), backed by broad unit/integration test additions and schema/docs updates.

Changes:

• Add new app-installations management flow (enterprise-auth client, delta/full reconciliation, reporting subject support).
• Add settings generation tooling (SettingsGenerator, CLI + repository_dispatch handler) and repo-selection utilities.
• Improve diff/sync behavior (additive mode, ruleset/teams/variables/custom properties updates) and update schema/docs accordingly.

Show a summary per file

File	Description
test/unit/lib/settingsGenerator.test.js	New unit tests for SettingsGenerator helpers and output paths.
test/unit/lib/repoSelector.test.js	New unit tests for resolving repos via names/teams/properties/all.
test/unit/lib/plugins/variables.test.js	Expanded Variables plugin test coverage incl. nop behavior.
test/unit/lib/plugins/teams.test.js	Expanded Teams plugin tests for security-manager and external_group logic.
test/unit/lib/plugins/custom_properties.test.js	Update tests to use github.rest.repos custom properties APIs.
test/unit/lib/plugins/branches.test.js	Add nop-mode regression coverage for branch protection messaging.
test/unit/lib/plugins/appInstallations.test.js	New tests for app installation delta/full sync + additive/nop behavior.
test/unit/lib/mergeDeep.test.js	New regression tests for ruleset/array identity and string-assign bug fix.
test/unit/lib/appOctokitClient.test.js	New tests for enterprise org installations client batching/toggles.
test/integration/plugins/teams.test.js	Extend integration test to cover security-manager role/team filtering.
test/integration/common.js	Fix Probot init for newer API and stub startup installation listing.
script/build-schema	Augment dereferenced schema with ruleset name/slug aliases.
schema/settings.json	Expand schema: teams include/exclude/external_group, new plugins/keys.
package.json	Add smoke-test npm scripts.
package-lock.json	Dependency lock updates (e.g., js-yaml, shell-quote).
lib/settingsGenerator.js	New SettingsGenerator to emit YAML from live GitHub state.
lib/repoSelector.js	New RepoSelector helper for fixed repo selection criteria.
lib/plugins/variables.js	Refactor Variables plugin: deterministic comparisons, nop commands.
lib/plugins/teams.js	Add external_group linking + updated security-manager handling.
lib/plugins/rulesets.js	Add name→id resolution + override placeholder resolution + idempotent create.
lib/plugins/repository.js	Add change signals for suborg re-evaluation (hasChanges/renamed/created).
lib/plugins/diffable.js	Add additive mode + per-plugin hasChanges signal + override resolution hook.
lib/plugins/custom_repository_roles.js	New plugin to manage custom repository roles at org level.
lib/plugins/custom_properties.js	Normalize entries robustly and switch to github.rest.repos APIs.
lib/plugins/branches.js	Fix nop messaging/logging for branch protection updates.
lib/plugins/appInstallations.js	New org-scoped plugin to manage GitHub App installation repo access.
lib/nopcommand.js	Extend NopCommand with subject/subjectType overload for reporting.
lib/mergeDeep.js	Improve identity/diffing: stable stringify fallback, bypass actor id quirks, parameters deletions.
lib/configManager.js	Stop swallowing getContent errors; rely on outer error handling.
lib/commentmessage.js	Replace legacy per-repo table with richer summarized check-run output.
lib/appOctokitClient.js	New enterprise-level Octokit wrapper for org installation endpoints.
index.js	Major sync refactor: enterprise context enrichment, selected sync dedupe, PR file detection changes, generator PR flow, installation_target handler.
generate-settings.js	New standalone CLI to generate YAML to local filesystem.
docs/sample-settings/suborg.yml	Document disable_plugins at suborg layer.
docs/sample-settings/settings.yml	Document disable_plugins/additive_plugins + ruleset name/slug aliases.
docs/sample-settings/sample-deployment-settings.yml	Document deployment-layer disable_plugins.
docs/README.md	Link to root README disable_plugins documentation.
docs/github-settings/4. teams.md	Document external_group/include/exclude semantics for teams.
docs/deploy.md	Note custom org roles permission requirement.
docs/adr/README.md	New ADR index.
docs/adr/0001-app-installation-plugin.md	New ADR describing app_installations design and rationale.
app.yml	Add repository_dispatch event + permissions for new features/APIs.
.gitignore	Ignore all *.env files.

Review details

Tip

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

Suppressed comments (1)

lib/plugins/teams.js:358

• The idempotency GET for current external-group links also uses team_slug: attrs.name, which will not match when config uses a team display name. This can cause the PATCH to run every time (or fail) even when the team is already linked.

      const current = await this.github.request(`GET ${teamExternalGroupsEndpoint}`, {
        org: this.repo.owner,
        team_slug: attrs.name
      })

• Files reviewed: 46/50 changed files
• Comments generated: 5
• Review effort level: Lite