diff --git a/AGENTS.md b/AGENTS.md index ec1a6d5..7c1bae9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,16 +3,18 @@ - This repository holds Atrinik's settings baseline (`baselines/atrinik.json`) and the read-only check that compares it with the live organization (`check_settings.py`). Read `README.md` first. -- Run the check before and after any settings change, and report any +- Run the check before and after any Atrinik settings change, and report any difference you did not cause first: `python3 check_settings.py baselines/atrinik.json`. Exit 0 is a match, 1 differences, 2 only "could not verify", 3 could not run. The organization webhooks line is expected: the everyday login lacks `admin:org_hook`. - How a change is made: change the setting in GitHub under the owner's login, only when the current task authorizes that change; run the check; update - the baseline until the check is clean; open a pull request here that quotes - the clean output. Live state wins and the record catches up in the same - task. Never record a change first and apply it later. + the baseline for that change until the check shows no difference the task + caused; open a pull request here that quotes the output and explains each + remaining line. A difference you did not cause goes into the baseline only + with the owner's explicit approval. Live state wins and the record catches + up in the same task. Never record a change first and apply it later. - The check only reads. Never run its fix commands unless the current task authorizes that exact change. Never add code to it that writes, stores a token or runs on a schedule. @@ -20,9 +22,12 @@ most three repository profiles, about ten per-repository exceptions, about 500 lines, standard library only. If a change would cross one, simplify instead. -- Another organization's baseline can be checked by path. Keep a private - organization's baseline, its check output and its names out of this public - repository, its pull requests and its CI logs. Test fixtures are invented. +- Another organization's baseline is checked by path + (`python3 check_settings.py /path/to/its/baseline.json`), and its baseline + pull request goes to the repository that holds that baseline, not here. + Keep a private organization's baseline, its check output and its names out + of this public repository, its pull requests and its CI logs. Test fixtures + are invented. - The settings automation that used to live here (publisher, Project synchronizer, drift audit, Project health check, community-health generator, semantic release) was retired on 2026-11-14 by owner decision. diff --git a/README.md b/README.md index d6f0654..e4398e3 100644 --- a/README.md +++ b/README.md @@ -43,8 +43,9 @@ could not verify: orgs/atrinik webhooks: Not Found (HTTP 404) (the login lacks t | 2 | No difference, but something could not be verified. | | 3 | The check could not run: bad arguments, an invalid baseline, no `gh`, `gh` not logged in or its token rejected, an unreadable repository list, or any unexpected error, such as an API response or a baseline shape it does not know (the traceback goes to standard error). Exit 1 always means differences, never a crash. The run stopped and printed nothing on standard output, so any difference it had found is not shown: fix the cause and rerun it. A single read that fails or times out (for example one network blip) is a "could not verify" line instead, and the run goes on. | -The check never runs a fix itself. A fix command is a suggestion: when live -state is right and the record is out of date, update the baseline instead. +The check never runs a fix itself. A fix command is a suggestion: when the +difference comes from a change the task authorized or the owner approved, +update the baseline instead. Other uses: @@ -142,7 +143,7 @@ One JSON file per organization: | `required_check_ruleset`, `check_integration_id` | The template for the one-per-repository required-check ruleset (`{repository}` is replaced) and the App that must report the checks (15368 is GitHub Actions). | | `security_configurations` | Configurations by name, with `default_for_new_repos`. | | `profiles` | At most three repository profiles: `repository` (merge settings), `branch_rules`, `tag_rules`, `security_configuration`. | -| `repositories` | Every repository: its `profile`, its required `checks`, and rarely `overrides` of profile keys with a `why`. | +| `repositories` | Every repository: its `profile`, its required `checks`, and rarely `overrides` of profile keys with a `why`. An override of an object key, such as `repository`, changes only the entries it names. The merge is one level deep: a `branch_rules` override replaces all the parameters of each rule type it names, so list them all; a `tag_rules` override needs both `ref` and `rules`; and an override cannot remove an entry. | | `recorded` | Names only: `teams`, `apps`, `environments`, `webhooks`, `organization_webhooks`. | | `reminders` | Plain notes about credentials and Apps, such as rotation dates. Never checked. | @@ -158,8 +159,10 @@ Live state wins and the record catches up in the same task: 2. Make the change in GitHub, under the owner's login, only when the current task authorizes it. 3. Run the check again. It shows exactly what you changed. -4. Update the baseline until the check is clean, and open a pull request - here that quotes the clean output (or explains each remaining line). +4. Update the baseline for the change the task authorized, until the check + shows no difference the task caused, and open a pull request here that + quotes the output and explains each remaining line. A difference you did + not cause goes into the baseline only with the owner's explicit approval. Changes made by hand in GitHub's web pages show up at the next run. GitHub keeps its own history too: the organization audit log and each ruleset's diff --git a/baselines/atrinik.json b/baselines/atrinik.json index 707c7fd..4a30ee5 100644 --- a/baselines/atrinik.json +++ b/baselines/atrinik.json @@ -2,7 +2,7 @@ "organization": "atrinik", "notes": [ "Atrinik's settings baseline, read by check_settings.py. Written from the live organization on 2026-11-14, after the changes the owner approved that day.", - "Live state wins: change the setting first, run the check, then update this file in a pull request that quotes the clean output.", + "Live state wins: change the setting first, run the check, then update this file in a pull request that quotes the check's output and explains each remaining line.", "\"recorded\" holds names only. A difference there means something changed since it was last recorded, not that it is wrong.", "\"reminders\" are plain notes for the owner. The check never reads them and never fails on a date." ], @@ -561,7 +561,7 @@ "reminders": [ { "item": "App atrinik-classic-dependency-updater (classic: variable DEPENDENCY_UPDATE_APP_ID, secret DEPENDENCY_UPDATE_APP_PRIVATE_KEY)", - "note": "Key rotation was due 2026-11-09. The key still works. Rotate it next time you are at Lyra, or decide it can wait." + "note": "Key rotation was due 2026-11-09. The key still works. Rotate it next time you are at your workstation, or decide it can wait." }, { "item": "App atrinik-crate-dependency-update (client: variable CRATE_DEPENDENCY_UPDATE_APP_ID, secret CRATE_DEPENDENCY_UPDATE_APP_PRIVATE_KEY)", diff --git a/check_settings.py b/check_settings.py index 2cb846b..d6ba672 100644 --- a/check_settings.py +++ b/check_settings.py @@ -169,8 +169,11 @@ def expected_rulesets(base): def profile_for(base, entry): + """The repository's profile with its overrides. An object override changes only the entries it names.""" profile = copy.deepcopy(base["profiles"][entry["profile"]]) - profile.update(copy.deepcopy(entry.get("overrides", {}))) + for key, value in copy.deepcopy(entry.get("overrides", {})).items(): + merge = isinstance(value, dict) and isinstance(profile.get(key), dict) + profile[key] = {**profile[key], **value} if merge else value return profile @@ -357,7 +360,8 @@ def check_repositories(self, live_repos): for name in names: profile, entry = profile_for(self.base, wanted[name]), wanted[name] repo = self.read(f"{org}/{name}", f"repos/{org}/{name}") - if repo is None: + if repo is None: # nothing about it was read, its team grants included + unread.add(name) continue self.compare_fields(f"{org}/{name}", profile.get("repository", {}), repo, lambda key, value, n=name: gh_command("PATCH", f"repos/{org}/{n}", {key: value}), diff --git a/tests/test_check_settings.py b/tests/test_check_settings.py index 1d12799..7a67f57 100644 --- a/tests/test_check_settings.py +++ b/tests/test_check_settings.py @@ -248,6 +248,22 @@ def test_unreadable_tag_ruleset_is_only_unverifiable(self): self.assertEqual(code, 2) self.assertEqual(lines, [f"could not verify: {ORG}/docs tags refs/tags/v[0-9]*: Forbidden (HTTP 403)"]) + def test_an_unreadable_repository_is_only_unverifiable(self): + """Its team grants were not read either, so they are not reported as gone.""" + self.api[f"repos/{ORG}/docs"] = {"__error__": "net/http: TLS handshake timeout"} + code, lines = self.run_check() + self.assertEqual(code, 2) + self.assertEqual(lines, [f"could not verify: {ORG}/docs: net/http: TLS handshake timeout"]) + + def test_an_object_override_changes_only_the_fields_it_names(self): + self.base["repositories"]["engine"].update(overrides={"repository": {"delete_branch_on_merge": False}}, + why="test") + self.api[f"repos/{ORG}/engine"].update(delete_branch_on_merge=False, allow_merge_commit=True) + code, lines = self.run_check() + self.assertEqual(code, 1) + self.assertEqual(len(lines), 1, lines) + self.assertLine(lines, f"{ORG}/engine: allow_merge_commit is true, baseline false") + def test_one_timeout_keeps_the_other_differences(self): self.api[f"orgs/{ORG}"]["members_can_create_teams"] = True self.api[f"repos/{ORG}/engine/hooks?per_page=100"] = {"__error__": "Get ...: dial tcp: i/o timeout"}