feat: adopt safe-settings for repository configuration management

[marcusburghardt]

Summary

Adopt github/safe-settings as a complementary tool to peribolos for managing the complytime GitHub org. Peribolos continues to own org membership, teams, and team-to-repo permissions. Safe-settings manages repository settings, rulesets, branch protection, and security configurations via GitOps.

What's included

• OpenSpec change proposal (openspec/changes/adopt-safe-settings/): design with 10 decisions, 7 specs, phased task list
• Safe-settings configuration (safe-settings/): org-wide defaults, two rulesets (safe-settings: code repos and safe-settings: non-code repos), complyctl 2-approver override, deployment settings with override validators. Derived from auditing the current GitHub state of all repos.
• GitHub Actions workflow (safe_settings_sync.yml): workflow_dispatch only with dry-run (default true) and repos (optional filter) inputs
• Boundary tests (config/boundary_test.go): 5 Go tests validating cross-tool consistency between peribolos and safe-settings
• Documentation: MAINTAINING.md (tool boundary, workflows, troubleshooting), README.md link, CODEOWNERS path rule, Makefile targets

Related Issues

• OpenSpec change: openspec/changes/adopt-safe-settings/

Design Note: workflow_dispatch-only Initial Rollout

safe-settings is a GitHub App (Probot-based) that reads its configuration from the admin repo's default branch via the GitHub API, not from the local filesystem. This is an architectural constraint: the ConfigManager fetches settings.yml, suborgs/, and repos/ through octokit.repos.getContent(), and the full-sync entry point (syncInstallation) does not accept a branch ref parameter.

This means:

• Config must be merged to main before safe-settings can read and apply it
• There is no local dry-run capability against local config files
• There is no built-in CONFIG_REF or similar env var to point at a feature branch

Given these constraints, the workflow starts with workflow_dispatch only (no push or schedule triggers) so that after merge:

1. Admins dry-run against a single repo first (repos=complytime-demos, dry-run=true)
2. Apply to that single repo (dry-run=false) and verify in the GitHub UI
3. Expand progressively to more repos
4. Only after full validation, enable push and schedule triggers in a follow-up PR

The repos input dynamically generates a scoped deployment-settings.yml at workflow runtime, restricting safe-settings to only the specified repositories.

Review Hints

• Review commits in sequence, each builds on the previous:

  1. docs: spec proposal (design decisions, specs, tasks)
  2. feat: safe-settings YAML config (settings, rulesets, suborgs)
  3. fix: spec review findings (alignment fixes)
  4. feat: implementation (workflow, tests, docs, Makefile)
  5. fix: org admin permission correction (feedback from @sonupreetam)

• After merge, test with: Actions > "Safe Settings Sync" > Run workflow > dry-run=true, repos=complytime-demos

• Boundary tests validate cross-tool consistency locally with no credentials needed: make test-unit

• Full local validation: make sanity

• Prerequisites already completed: GitHub App registered (ID: 3796583), credentials stored, "verifiy" ruleset renamed to "verify".

[marcusburghardt]

@sonupreetam it would be great to have your eyes on this PR since you also researched about alternative solutions. WDYT?

[sonupreetam]

@marcusburghardt This looks good to me, thank you for tagging me on this. The org-level rulesets from settings.yml close the enforcement gap I was worried about (repo admins can't delete them).

Previously, I had evaluated repository-settings-action (rejected legacy branch protection API only, per-repo model, doesn't support rulesets), looked at org-level rulesets via direct gh api scripts, and had a phased rollout plan sketched out (central YAML → reconciliation script → Enterprise org-level rulesets for immutability). safe-settings lands in a similar place architecturally but with a maintained engine instead of a custom script, which I think is the right trade-off.

I noticed while briefly reviewing:

• App permissions: The design doc says Organization Administration: read, but creating org-level rulesets (which is what settings.yml rulesets do via POST ) might require write. May be docs could be stale.

Happy to discuss further or put the formal review on the PR whenever you're ready.

[marcusburghardt]

Good catch. Creating org-level rulesets via POST /orgs/{org}/rulesets requires Organization Administration: write, not read. Updated the design doc, deployment spec, and task list in 1566739. The GitHub App permissions should also be updated to match — will verify before the first workflow run.

[marcusburghardt]

@jpower432 and @jflowers , I would appreciate your reviews on this. I plan a gradual adoption, starting manually until a few (less critical) repositories are well tested then move to fully automated. This should reduce the maintenance burden while allowing a centralized and transparent enforcement of our relevant settings.

[marcusburghardt]

Just rebased using GH interface.

[marcusburghardt]

Rebased again using the GH Web Interface.