🎙️ task - feat: support github rulesets at org and repo level

[ehm-a-beaver]

🦫🎙️ dispatch to foreman

💧 task enqueued
   ├─ priority = ?
   ├─ yieldage = ?
   └─ leverage = ?

title
feat: support github rulesets at org and repo level
description

.what

add support for github rulesets at both repo level and org level, so consumers can declare tag-protection (and branch) rulesets as code via the declastruct get/set pattern.

.why

use case from ahbode/infrastructure: enforce that only a specific github app (release-please) can create tags that match v*. this is the out-of-band half of an aws oidc "prod apply only from a version tag cut from main" guarantee:

• aws sts conditions on ref_type == tag + ref LIKE refs/tags/v*
• a github tag ruleset must restrict v* creation to the release app only (bypass actor)
• release-please runs only on main

today declastruct-github has no ruleset/tag-protection resource (it models DeclaredGithubBranchProtection + DeclaredGithubEnvironment but not rulesets), so this cannot be declared as code.

.deliverables

1. DeclaredGithubRepoRuleset domain object (repo-scoped)
2. DeclaredGithubOrgRuleset domain object (org-scoped; adds repository-scope conditions)
3. supporter value objects if the repo favors that granularity (rule, bypass actor, conditions) — mirror how DeclaredGithubBranchProtection handles nested shapes
4. DeclaredGithubRepoRulesetDao + DeclaredGithubOrgRulesetDao — get (by primary id, by unique name, by ref) + set (findsert + upsert), to mirror extant DAO idempotency
5. register/export alongside extant objects + DAOs (no barrel-export forwarders)
6. tests to mirror extant DAO tests (unit for cast logic; integration per the repo's test-fns + credentials pattern)

.api reference

• repo rulesets: GET/POST/PUT/DELETE /repos/{owner}/{repo}/rulesets (+ /rulesets/{id})
• org rulesets: GET/POST/PUT/DELETE /orgs/{org}/rulesets (+ /rulesets/{id})
• ruleset fields: name (natural unique key per scope), target ('branch'|'tag'|'push'), enforcement ('active'|'evaluate'|'disabled'), bypass_actors[] (actor_id, actor_type ['Integration'|'Team'|'OrganizationAdmin'|'RepositoryRole'|'DeployKey'], bypass_mode ['always'|'pull_request']), conditions (ref_name.include[]/exclude[], e.g. refs/tags/v*, meta ~ALL/~DEFAULT_BRANCH), rules[] ({ type, parameters? }; types: creation, update, deletion, required_signatures, required_linear_history, non_fast_forward, ...)
• org rulesets also support conditions.repository_name (include/exclude/protected) or repository_id
• id = server-assigned primary key; name = natural unique key (per repo, or per org)

.key choices to verify

• repo ruleset: primary = ['id'], unique = ['name']
• org ruleset: confirm name uniqueness is per-org; key accordingly
• mirror exactly: DeclaredGithubBranchProtection, DeclaredGithubEnvironment, and their DAOs (names, file layout, cast functions, context/auth shape, get/set verbs, inline io types, one-export-per-file, fail-fast)

.note

• honor the repo's house rules under .agent/ and briefs/
• get typecheck/build + lint/format green
• write integration tests per the repo's pattern even if creds are unavailable locally; never add failhide/skip stubs

.source

requested from ahbode/infrastructure work on github-environments-vs-aws-oidc (vlad).