Skip to content

Canary set-up: the ruleset, code owners and identities the trials need #24

Closed

Description

@don-petry

Part of the epic "Epic: slice 1, first approval. A Release on next reviews a pull request to this repo, and the machine user's approval stands" (moved from slice 0 on 2026-10-21, oversight steering point 3).

Why. The canary is empty. The approval-mechanics trials need a repo that behaves as the Factory's will, and none of the three planned Apps may author or push.

Done when

  • The canary has a ruleset on its default branch like the one the Factory's repo will have once review is required: code-owner review, approval of the last push, and the rule for unattributed changes.
  • A code owners file names the machine user for one path and the Maintainer alone for another.
  • The machine user is a collaborator with write access, and holds one fine-grained token scoped to the canary alone, short-lived, stored as an environment secret restricted to the default branch.
  • One trial-only App that can push and open pull requests is installed on the canary and nowhere else.

Needs. From the Maintainer: the collaborator, the token and the App. The third criterion waits on trial P-3's verdict. Settings on the canary are changed only on the Maintainer's word.

Design. §6, P-1, P-7 and P-24; §5.1; §4.9, the machine user's token.

Activity

  1. don-petry commented on Oct 14, 2026

    @don-petry
    ContributorAuthor

    A ruling that bears on this story. On 2026-10-14 the Maintainer ruled that the Factory's repo copies the org's code owners file word for word: the team org-leads owns every path, the Factory's own rules included. Decision 0005 and the design (§1.1, §5.1, §9.12) are edited to match in the pull request "Context for the Factory's authors: lessons, standards, decisions and the checks that hold them".

    So trial P-24 (the Maintainer as the only code owner of a path) is no longer needed for the Factory's repo; the design now says so beside it. Whether the canary still wants a path owned by the Maintainer alone is this story's call: the second "Done when" item depends on it.

  2. don-petry commented on Oct 18, 2026

    @don-petry
    ContributorAuthor

    Working rulings (overturnable in review)

    Solution Architect, 2026-10-17. The canary today: no ruleset, no code owners, main-only done (DONPETRY_BOT, reviewer don-petry, branch main, admin bypass off). Its workflow token can write and approve.

    1. The ruleset. One ruleset, main, on ~DEFAULT_BRANCH, active, no bypass actors. Rules: deletion, non-fast-forward, and a pull-request rule with one approval, code-owner review, approval of the last push, the extra approval for unattributed changes, stale approvals dismissed on push, squash only. Why: it is the Factory's ruleset once review is required. A bypass actor makes a merge prove nothing.

    2. No required check and no merge queue yet. Why: the trials read reviewDecision and mergeStateStatus; only review may block. P-2 adds both in its own story.

    3. Code owners. .github/CODEOWNERS holds * @combsmith/org-leads and /p24/ @don-petry. Why: the Factory's file names the team, so P-7 runs against the file the Factory has. This amends the second criterion. P-24 stays, at one line: the skill stops batch 2 while a batch-1 trial lacks a fixture.

    4. Identities. The machine user keeps its access through org-leads, as on the Factory's repo; no collaborator is added. Its token is fine-grained, on the canary alone, with Pull requests write and Metadata read. It lasts 7 days at most, for one trial window, and is revoked at the window's end. The trial-author App (5363178) is on the canary alone. Why: the least that approving takes, in a public repo every org member can push to.

    5. The workflow token. Read-only by default, and it may not approve. Why: as on the Factory's repo; a second approver would spoil P-1 and P-7.

    6. How an App pushes with no session minting a token. At the Maintainer's terminal. A session drafts a script; the Maintainer reads it and runs it. It mints the token from the local key, pushes, opens the pull request, reads GET /installation/repositories, and revokes the token. Raw responses go to a scratch directory outside the repo. Why: the key is already there, and a writing key does not belong in a public repo.

    7. How the machine user approves. A canary workflow, machine-user-approves.yml: workflow_dispatch on main with the PR number as input, environment main-only, permissions: {}. It prints only the review's id, state, commit and author. Why: the token stays in the environment, and each use waits for the Maintainer's click.

    8. A run counts only if the machine user's is the only approval on the head. Why: org-wide third-party Apps can review the canary too.

    9. Order. Writes 1 to 5 below, ruleset last. Then P-1 (an App authors), P-7 (the Maintainer authors, the App pushes last), P-24 (an App's change under /p24/) and P-28 (last pusher, read on P-7's pull request). The Maintainer merges P-1's and P-7's; with no bypass, a merge is evidence. Unblocks P-1, P-7, P-24 and P-28 of batch 1, and the set-up P-2, P-5, P-25 and P-38 reuse.

    10. Decision records. None: trial set-up, on §4.9, §5.1 and the skill.

    Needs the Maintainer?

    Yes. Each write waits for his yes:

    1. Set the canary's workflow token to read-only, and stop it approving pull requests. Session, through his login.
    2. Confirm DONPETRY_BOT matches ruling 4, or mint it again and store it. Maintainer.
    3. Confirm the trial-author installation reaches the canary alone. P-1's first exchange records it. Maintainer.
    4. Push one commit to the canary's main as don-petry: .github/CODEOWNERS, p24/README.md and .github/workflows/machine-user-approves.yml. Session.
    5. Create the ruleset main of ruling 1. Session, through his login.
    6. At each window's end, revoke the machine user's token and delete DONPETRY_BOT. Maintainer.
    7. When batch 2's App trials are done, uninstall the trial-author App. Maintainer.

    The ruleset, code owners and approval workflow stay for batch 2. Org-members' push on the canary stays: the ruleset stops a direct push, and the reviewer guards the token.

    Approved by the Maintainer, 2026-10-18: writes 1, 4 and 5, made by a session through the Maintainer's gh login, and further canary changes as needed to proceed. Writes 2, 3, 6 and 7 stay the Maintainer's: every credential and App installation.

  3. don-petry commented on Oct 19, 2026

    @don-petry
    ContributorAuthor

    Set-up checked, 2026-10-19 ~03:10Z (read-only, through the Maintainer's login)

    The session's writes are made and match the rulings. Step 0 of the P-1/P-7/P-24 runbook passes.

    Write Ruling Read from GitHub Verdict
    1. Workflow token 5 default_workflow_permissions: read, can_approve_pull_request_reviews: false matches
    4. One commit to main 3, 7 d39a946, 2026-10-18 02:43Z. CODEOWNERS is * @combsmith/org-leads and /p24/ @don-petry. p24/README.md is there. machine-user-approves.yml is workflow_dispatch only, with permissions: {}, environment main-only and a main-only guard, and prints only the review's id, state, commit and author matches
    5. Ruleset main 1, 2 25328026, active, no bypass actors. Deletion, non-fast-forward, and a pull-request rule: 1 approval, code-owner review, last-push approval, extra approval for unattributed changes, stale approvals dismissed, squash only. No required check and no merge queue matches
    main-only 4, 7 branch main only, required reviewer don-petry, admin bypass off, one secret (DONPETRY_BOT, set 2026-10-17 23:56Z) matches
    Identities 4 org-leads is don-petry and donpetry-bot; no collaborator added; 0 open pull requests matches

    Still the Maintainer's:

    • Write 2. Confirm that DONPETRY_BOT is fine-grained, on the canary alone, with Pull requests write and Metadata read, and lasts 7 days at most. A session can't read a token's settings. It was set on 2026-10-17, so this trial window ends by 2026-10-24 at the latest.
    • Write 3. The trial-author installation (172549542) has repository_selection: selected. Which repos it reaches can't be read with a user login: GET /user/installations/{id}/repositories answers 403. The first exchange of the first tools/trial_as_app.sh run records it, as planned.

    Once both are confirmed, P-1 and P-7 (#14) can run.

  4. don-petry commented on Oct 19, 2026

    @don-petry
    ContributorAuthor

    The Maintainer confirmed (2026-10-19, in chat):

    • Write 2. DONPETRY_BOT matches ruling 4: fine-grained, on the canary alone, with Pull requests write and Metadata read, and lasting 7 days at most. It was set on 2026-10-17 23:56Z, so the trial window ends by 2026-10-24.
    • Write 3 is confirmed by the first exchange of the first tools/trial_as_app.sh run (GET /installation/repositories), as the runbook plans. That exchange is checked before anything else in P-1 counts, and P-1 stops if the App reaches more than the canary.

    The set-up is complete, and #14 (P-1, P-7) can run.

  5. don-petry commented on Oct 28, 2026

    @don-petry
    ContributorAuthor

    Second machine-user window (2026-10-27/28): the canary as it now stands, for later trials.

    • Ruleset 25328026 on main keeps the two rules the window added, by the Maintainer's choice, so P-37 (Trials P-35, P-36, P-37 and P-38: what a Lens's check is read from, the queue's base, and the approved commit #186) can use them: merge_queue (squash, ALLGREEN, one entry at a time, check timeout 15 minutes) and required_status_checks (p2-queue-check, strict off).
    • The window's workflows stay on main: p2-queue.yml (the queue's required check, slow on a merge group, failing where p2/eject is), p42-checks.yml (on p42/** only) and machine-user-approves.yml with its optional commit input.
    • The trial pull requests are closed and their branches deleted, except 63 until P-7.refused's last case runs. The DONPETRY_BOT window token is being revoked.

    🤖 Addressed by Claude Code

  6. don-petry commented on Oct 31, 2026

    @don-petry
    ContributorAuthor

    Ticked by the audit of epic #182, each read against main at 39a4837:

    • The canary has a ruleset on its default branch Read live on 2026-10-31: canary ruleset 25328026 is active on ~DEFAULT_BRANCH with no bypass actor, require_code_owner_review, require_last_push_approval and require_extra_approval_for_unattributed_changes all true.
    • One trial-only App that can push and open pull requests Read live on 2026-10-31: combsmith-sf-trial-author has repository_selection: selected, contents and pull requests write. trials/P-42.json records GET /installation/repositories answering one repo, the canary.

    The other boxes are left open: the audit could not show them holding on main.

    🤖 Audit of epic #182 by Claude Code

  7. don-petry commented on Nov 2, 2026

    @don-petry
    ContributorAuthor

    Ticked by a new audit of the epic, each read against main at 0a22436 or live on 2026-11-02:

    • A code owners file names the machine user for one path and the Maintai. Holds as a later ruling changed it: Overtaken by ruling 3 of 2026-10-18 on this issue: '.github/CODEOWNERS holds * @combsmith/org-leads and /p24/ @don-petry... This amends the second criterion', with the machine user a code owner through org-leads (ruling 4). Live read of combsmith/software-factory-canary .github/CODEOWNERS on main (4feefbc, 2026-11-01): * @combsmith/org-leads and /p24/ @don-petry. Live: org-leads members are don-petry and donpetry-bot. trials/P-24.json (pass): on a PR changing only p24/, the machine user's approval leaves reviewDecision not APPROVED and …
    • The machine user is a collaborator with write access, and holds one fi. Holds as a later ruling changed it: Overtaken by ruling 4 of 2026-10-18: 'The machine user keeps its access through org-leads... no collaborator is added. Its token is fine-grained, on the canary alone, with Pull requests write and Metadata read. It lasts 7 days at most, for one trial window, and is revoked at the window's end', and ruling 7 (environment main-only). The Maintainer confirmed it in chat on 2026-10-19 ('DONPETRY_BOT matches ruling 4'). Live: canary collaborators list donpetry-bot as write (via org-leads, no direct grant added); org-leads = don-petry, donpetry-bot. …

    Closed: all four boxes hold or were amended by its own rulings, and the canary stands as they say.

    🤖 Audit of epic #182 by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions