Declarative GitHub governance · Octoform 0.5
Make GitHub policy visible before it becomes real¶
Octoform compares an explicit YAML policy with the current state of your GitHub organization and its repositories, builds a deterministic plan, and applies only the changes you approve.
Governance is a reviewable workflow¶
Every run separates what you intend, what GitHub currently exposes, and what Octoform is actually allowed to change.
01 · Declare
Describe only what you manage¶
Omitted settings remain untouched, and nothing is removed because a line was left out. Defaults, repository types, and repository overrides resolve field by field into one effective policy.
02 · Review
See drift and blocked work¶
The plan identifies current and desired values, warnings, unsupported capabilities, and operations the supplied token cannot prove safe.
03 · Apply
Confirm deliberate changes¶
Octoform presents the planned operations before mutation and reports each outcome without treating unreadable state as permission to overwrite it.
Start with the smallest useful policy¶
The example manages two explicit settings and makes no claim about anything else. Produce a read-only plan before considering an apply:
Safety is part of the model¶
Omission means unmanaged¶
A short configuration cannot silently become an instruction to disable or delete settings you never declared.
Capability comes from evidence¶
Owner kind, repository visibility, token permissions, and GitHub responses decide whether an operation is available—not a hard-coded commercial plan name.
Uncertainty blocks mutation¶
If Octoform cannot read enough state to produce a trustworthy diff, the plan surfaces the block instead of inventing a safe-looking answer.
The account, not only its repositories¶
Octoform 0.5 governs the organization above the repositories: its profile, what members may do, its custom properties, the rulesets it aims at repositories it selects, its teams and its roles. All of it appears in the same plan, and all of it is confirmed the same way.
Reach is stated, not discovered¶
A base permission, an organization ruleset and an organization role each reach
every repository the account owns — including ones no policy names. Each is
reported as sensitive before it is applied.
Membership asks first¶
Inviting, removing or converting one person is a command that names them, says what will happen, and waits. An invitation is addressed to a person, not reconciled by a schedule.
Nothing is removed by omission¶
Every removable resource has a word that has to be written: none for a grant,
mode: absent for a team, a label or a property definition. Deleting a line
stops managing something; it never destroys it.
Current documentation: this site describes Octoform 0.5. Use the version
selector when operating another release line so commands, configuration, and
permissions remain aligned with the package you installed.