Skip to main content
Org rulesets defined once, in code, instead of click-ops repeated across every repo.
Language: HCL  ·  Status: active  ·  Last active: this week  ·  Source on GitHub
tofu-github puts the dryvist GitHub organization’s rulesets under OpenTofu, applied through the same Terrakube workspace pattern as the rest of the homelab. GitHub doesn’t auto-inherit CI or branch-protection config across repos. Org rulesets let dryvist define this once and apply it to every repo automatically.

What it manages

  • Push protection. A hard ceiling on file size and a banned-extension list, enforced at the git layer (no workflow run) on every repo and ref.
  • Branch protection. The org branch rules and git-flow rules keep required signatures, branch-name patterns, Conventional Commits rules, and no bypass. They do not require review threads to be resolved.
  • Docs publication. The separate docs-publisher ruleset guards the public docs repo; see Generated projection for the first-publication approval.
  • Upstream forks. Their rulesets are unchanged. A fork of a third-party project sets upstream_fork: true in config/repos.yml. Upstream history can’t meet the signature and commit-format rules, so the fork is exempt from them. Its default branch still requires a PR, allows merge commits only, and blocks deletion and force-push.
  • Review gate. The ruleset accepts the AI Merge Gate check only from the reviewer App. No person reviews before merge.
  • Markdown lint. Requires the markdownlint workflow (defined once in the org’s .github repo) to pass on every ref of every repo, with new repos exempted until their default branch exists.
  • Code scanning. An org ruleset requires CodeQL results on the default branch and main of every public, unarchived, non-fork repository in the org. The same set gets its CodeQL default setup from this repo. A repository that changes from private to public gets secret scanning, push protection and CodeQL default setup on the apply after the one that changes its visibility. GitHub refuses those features on a private repository while the account’s metered-usage lock is on.
  • Default branch. A git-flow repository gets develop as its default branch. When the branch is already the default, a data-driven import block adopts it into state and OpenTofu makes no call.
  • Repository family. family is an optional single-select repository property. Only a repository whose repos.yml entry sets a family receives a value. All others stay unset.
  • Labels. labels.yml is the one label definition, and OpenTofu applies it to every unarchived repo, forks included. A moved block moves the label state to the org-wide resource address. A data-driven import block adopts labels that already exist on a repo, matched case-insensitively by name, and creates the rest.
  • Repo settings. Every unarchived repo is governed by default: auto-merge on, delete-branch-on-merge on, and vulnerability alerts on. All 76 unarchived repos carry these settings.

Merge tier

Every repository has a custom property merge_tier with the value standard or hot; see Branch conventions for what each tier means. It is set per repository in config/orgs/<owner>/repos.yml in the governance repository. OpenTofu applies the property and the queue ruleset of a hot repository in one apply. Setting a repository back to standard removes its queue ruleset in the same apply; that is the rollback. One variable, merge_tier_override, forces every repository to standard in one apply. Organisation settings are code: they are declared here and applied from a reviewed plan, never clicked.

How it fits

Org-wide GitHub governance only: rulesets, required workflows, labels, and repo settings. It doesn’t change what any individual repo’s CI pipeline does. See CI/CD policy for that layer.

Getting started

1

Clone and enter the dev shell

git clone git@github.com:dryvist/tofu-github.git && cd tofu-github && direnv allow
2

Required environment

  • TF_CLOUD_HOSTNAME: workspace hostname.
  • GITHUB_TOKEN: provider credential.
3

Plan and apply

tofu init && tofu plan && tofu apply runs plan and apply remotely in Terrakube. Output streams back to the local shell.

tofu-proxmox

Same OpenTofu-through-Terrakube pattern, applied to the Proxmox cluster instead of GitHub.

tofu-unifi

Same pattern again, applied to the UniFi controller’s data plane.

CI/CD policy

CI/CD conventions enforced by these org rulesets.

Source on GitHub

Ruleset definitions, config thresholds, full README.