Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 12 additions & 7 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,26 +3,31 @@
- 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.
- Keep within its limits: nothing that writes, no dates that fail it, at
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.
Expand Down
13 changes: 8 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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. |

Expand All @@ -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
Expand Down
4 changes: 2 additions & 2 deletions baselines/atrinik.json
Original file line number Diff line number Diff line change
Expand Up @@ -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."
],
Expand Down Expand Up @@ -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)",
Expand Down
8 changes: 6 additions & 2 deletions check_settings.py
Original file line number Diff line number Diff line change
Expand Up @@ -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


Expand Down Expand Up @@ -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}),
Expand Down
16 changes: 16 additions & 0 deletions tests/test_check_settings.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"}
Expand Down
Loading