Decide and apply a workable branch ruleset strategy

[matt-edmondson]

Context

The Terraform workspace that manages this org's repository settings is built and validated, but no branch ruleset has been applied anywhere. The original design called for a strict ruleset (require a PR, require Build, Test & Release, block deletion and force-push) with github-actions[bot] as a bypass actor so KtsuBuild's release push to main would still work.

That design is not implementable. GitHub rejects it:

HTTP 422: Actor GitHub Actions integration must be part of the ruleset source or owner organization

orgs/ktsu-dev/installations lists only azure-pipelines (9426), sonarqubecloud (12526), claude (1236702), and ktsu-homelab-arc-runners (3409675). GitHub Actions is not an installed app, so it cannot be a bypass actor.

The 15368 value in the original design was a mistake. It was read from ImGuiApp's old ruleset, where it appears as integration_id inside required_status_checks, which names the app that reports a check. A bypass actor requires an app installed in the org. Different requirement.

The rest of the ruleset shape is valid. A ruleset with deletion, non_fast_forward, and pull_request, bypassed by RepositoryRole 5, was created and deleted successfully during testing.

Why it matters

github-actions[bot] holds write, not admin, so the RepositoryRole 5 bypass does not cover it. Any ruleset carrying a pull_request rule blocks KtsuBuild's metadata push to main and breaks releases across every repo it is applied to.

Options

1. Guardrails only. Keep deletion and non_fast_forward, drop pull_request and required_status_checks. Neither blocks a fast-forward push, so releases are unaffected and no bypass is needed. Zero changes required, applies cleanly today.
2. Stop committing derived metadata to main (see the KtsuBuild issue). Removes the push entirely, after which the strict ruleset works with no bypass actor at all.
3. Strict plus an admin PAT in every workflow, so pushes come from an admin covered by RepositoryRole 5. Not recommended: a long-lived admin PAT stored as a secret in 60 repos is a worse security position than the ruleset is worth.

Acceptance criteria

• A strategy is chosen and recorded
• github/rulesets.tf reflects it
• The ruleset is applied to one pilot repo and verified against the live API
• A real release is confirmed to still succeed on that repo before wider rollout

State today

github/checks.tf and github/rulesets.tf are committed but applied nowhere. No repo in the org has an active ruleset. ImGuiApp's previous ruleset was deleted because it was inert, its conditions.ref_name.include was an empty list, so it matched no branch and enforced nothing.

[matt-edmondson]

Related work: #6 unblocks the strict option by removing the push to main entirely. #5 must land before any ruleset requiring Build, Test & Release is rolled out to the repos still carrying the pull_request paths-ignore, or PRs there become unmergeable.

[matt-edmondson]

Triage

Priority: High Effort: Small

What needs to be done: Choose a branch ruleset strategy now that the original strict design (GitHub Actions as bypass actor) is confirmed unimplementable, and apply it to a pilot repo.

Suggested next steps / acceptance criteria:

• Ship option 1 (guardrails only: deletion + non_fast_forward, no pull_request/status-check requirement) now — it needs no bypass actor and applies cleanly today
• Treat the strict ruleset (option 2, via Stop committing derived metadata to main in KtsuBuild #6) as the real long-term target rather than the admin-PAT workaround (option 3), which trades one risk for a worse one
• Apply to one pilot repo and verify against the live API before wider rollout

Blockers / dependencies: Related to .github#6 (removing the metadata push unblocks the strict option with no bypass actor needed) and .github#5 (must land first if any ruleset requires the Build, Test & Release check, or .md-only PRs become unmergeable)

---

Generated by Claude Code