Skip to content

Commit bfc93d4

Browse files
chore(governance): stop declaring repository identity in settings.yml (#73)
`probot/settings` applies this file on **every push to the default branch**, so the four identity keys it declared are instructions, not documentation. The estate has already paid for exactly this: `.github/settings.yml` once read `name: "{{REPO}}"`, GitHub collapsed the illegal braces to dashes, the repository renamed itself to `-REPO-` on every push, its old URL 404'd, and it was read as a deleted repository. This repo still declared `name`, `description`, `homepage` and `private`. The repair is convergence on the source of truth, not new content: - the header becomes the template's own header, which documents the incident and the rule ("THIS FILE MUST NEVER DECLARE REPOSITORY IDENTITY"); - the four identity keys are removed; **everything else is unchanged** — same repository settings, same 18 labels; - repository identity and visibility stay set out of band, once, by the owner. Verified with the estate's own gate, `scripts/check-no-placeholders.sh`, whose settings.yml guard runs in template repos too (that exemption is how the original incident went unseen). On this branch the guard reports clean.
1 parent 865a4c5 commit bfc93d4

1 file changed

Lines changed: 58 additions & 5 deletions

File tree

‎.github/settings.yml‎

Lines changed: 58 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,15 +7,45 @@
77
# applied by the probot/settings app when changes are pushed to the default
88
# branch. Install the app at: https://github.com/apps/settings
99
#
10-
# Template file — replace nesy-solver and Live proof playground for neurosymbolic theorem provers with actual values.
10+
# ─── THIS FILE MUST NEVER DECLARE REPOSITORY IDENTITY ─────────────────────────
11+
#
12+
# It carries NO `name`, `description`, `homepage` or `private` key, and it must
13+
# never gain one. The reason is a real incident, not a hypothetical:
14+
#
15+
# This file previously read `name: "{{REPO}}"`. probot/settings applies it on
16+
# every push to the default branch, so it submitted the literal string
17+
# `{{REPO}}` as the repository name. GitHub sanitises an invalid name by
18+
# collapsing each run of illegal characters to a dash — `{{REPO}}` became
19+
# `-REPO-`. The template renamed itself on every push, its old URL 404'd, and
20+
# it was mistaken for a deleted repository. `description` was likewise left
21+
# reading the literal `{{DESCRIPTION}}` on the live repo.
22+
#
23+
# Two properties make identity keys unsafe here specifically:
24+
#
25+
# 1. This is a TEMPLATE. `just repo-init` fills placeholders in repos minted by the
26+
# scaffolder — but GitHub's "Use this template" button copies the default
27+
# branch verbatim and never runs `just repo-init`. Any placeholder left in a
28+
# probot-managed file therefore reaches children unrendered.
29+
# 2. Identity is not shareable. The template must be public while children
30+
# default private; a child cannot inherit either `name` or `private` from
31+
# its parent without being wrong.
32+
#
33+
# Repository identity and visibility are therefore set OUT OF BAND: once per
34+
# repo, at creation time, by the operator (the Configure stage of ADR-0003).
35+
# `just repo-init` deliberately runs NO `gh` commands — it prints the exact
36+
# `gh repo edit` commands as next steps instead. Fail-closed default: repos
37+
# stay private unless the owner flips visibility deliberately; the template's
38+
# own name and visibility are set deliberately by the owner.
39+
#
40+
# Everything below is safe to inherit: it is true of every RSR repo regardless
41+
# of that repo's name, purpose or visibility.
42+
#
43+
# Enforced by `scripts/check-no-placeholders.sh`, which fails if this file
44+
# contains a `{{` token or declares any of the four identity keys.
1145

1246
# ─── Repository Settings ───────────────────────────────────────────────────────
1347

1448
repository:
15-
name: "nesy-solver"
16-
description: "Live proof playground for neurosymbolic theorem provers"
17-
homepage: "https://github.com/hyperpolymath/nesy-solver"
18-
private: false
1949
has_issues: true
2050
has_projects: true
2151
has_wiki: false
@@ -105,3 +135,26 @@ labels:
105135

106136
# ─── Branch Protection ─────────────────────────────────────────────────────────
107137

138+
# A required context must name a check that is actually EMITTED, or the branch
139+
# deadlocks: the check never reports, so it stays permanently pending, and with
140+
# enforce_admins even the owner cannot merge or push. This block previously
141+
# required three contexts, two of which no repo has ever emitted —
142+
#
143+
# "codeql" is emitted as `analyze (actions, none)` (job id + matrix)
144+
# "hypatia-scan" is emitted as `scan / Hypatia Neurosymbolic Analysis`
145+
# (a reusable-workflow call always reports `caller / called`)
146+
#
147+
# — while "openssf-compliance" resolved only because its job *id* is literally
148+
# `openssf-compliance` and it declares no `name:` and no matrix. That is the
149+
# rule: pin the job **id** to the context string. Note this file is applied by
150+
# probot on every push to the default branch, so a wrong context here does not
151+
# merely describe protection, it re-imposes the deadlock on every push.
152+
#
153+
# `contexts` is deliberately EMPTY rather than aspirational. Requiring a check
154+
# that cannot pass is the same defect as requiring one that cannot report, and
155+
# on this repo no check can currently run at all: GitHub Actions is billing-
156+
# blocked for PRIVATE repositories on this account ("The job was not started
157+
# because recent account payments have failed or your spending limit needs to be
158+
# increased"), which is why every workflow here fails with zero steps while the
159+
# estate's public repos run normally. Repopulate this list — one context at a
160+
# time, each pinned to a job id, each verified green — once Actions can run.

0 commit comments

Comments
 (0)