GCSS-1391: validate organisation/*.yaml before plan

[dev-milos]

Implements the schema-validation half of GCSS-1391. The separate workspace/state half is a follow-up PR.

What this does

Validates the organisation teams.yaml and members.yaml on every PR, before Terraform plan, so a bad org config fails fast with a clear message instead of erroring at apply — or worse, planning a member wipe that reads as a clean plan.

Two layers, mirroring how repos/*.yaml is already validated:

• JSON schema — shape, enums and lengths (visibility is visible|secret, role is owner|member, names are non-empty), reusing the existing validateFile machinery.
• Cross-file rules the schema cannot express — reusing the already-built, already-tested TeamsConfig.Validate() / MembersConfig.Validate(), which until now were called from nowhere but tests:
  • a member referencing a team not defined in teams.yaml
  • duplicate team names / duplicate team memberships
  • a protected owner being removed or demoted from owner

Both config locations are validated

Terraform reads org config from two places and merge()s them — organisation/ and the bootstrap importer's staged importer_tmp_dir/organisation/. Validation reads and merges both the same way, so:

• staged bootstrap output is schema-checked and cites its real path
• a staged member may reference an already-promoted team without a false positive
• the protected-owner check sees the merged, effective config, not either file alone

Without this, the bootstrap import PR — the one that first hands GCSS ownership of the org, and the highest-stakes plan in the feature — would be the single plan receiving no checks at all.

An absent members.yaml is not a bypass

Terraform reads a missing members.yaml as members: [], so deleting the file plans the same org-wide member wipe as emptying it. Both are now rejected identically; validation loads an absent file as an empty config rather than skipping the check. git rm organisation/members.yaml does not sail through.

Protected owners and schemas both come from deployment config

--protected-owners is threaded from a protected_owners workflow input (intended to come from a repo/org Actions variable) and is never read from a file inside the config repo — otherwise a PR could edit its own guard away.

For the same reason, and unlike repository config, the org path deliberately does not honour a config-repo schema override (resolveOrgSchema). Both the rules and the list of who they protect are deployment config, so a pull request cannot weaken what it is validated against.

When no protected owners are configured the run warns rather than passing silently, so an operator can tell an enforced run from an unconfigured one.

What's included

• validate-org command — orchestrates both layers over both locations.
• compileSchema + loadYAMLDocument / validateInstance — factored out of validate.go so the repository, teams and members paths share one schema compiler and one YAML parse, rather than each file being read and parsed once per layer.
• validate-org-configs composite action — mirrors validate-repo-configs.
• Wiring — one extra step in the existing validate job in tf-plan.yaml, reusing its checkouts; terraform-plan still needs: validate.
• minLength: 1 on team name, member username and team-membership name — required only checks presence, so name: "" previously produced a resource keyed by the empty string.
• Tests — 19 cases, including the deleted-members-file guard, staged-config validation, promoted-over-staged merge precedence, empty names, the no-cascade behaviour when teams.yaml fails to parse, and the file-based schema path the composite action actually uses in CI.

Testing

• go build / go vet / go test ./... pass; schemas regenerate with no drift; workflow and action YAML parse.
• Verified end-to-end on a test org, both directions:
  • bootstrap PR with staged files → ok -- organisation config (the log line confirms it validated the staged files rather than skipping) → plan 1 to import, 0 to add, 0 to change, 0 to destroy
  • PR with no members file and PROTECTED_OWNERS set → protected owner "…" is missing from members.yaml, validate job failed, terraform-plan skipped

A conscious sequencing call

Org validation is added to the shared validate job that terraform-plan depends on. Until the workspace split lands, that means a broken organisation/members.yaml blocks the plan for a PR touching only repos/*.yaml — the shared blast radius #1391 exists to remove, present at the CI layer.

This is deliberate rather than overlooked. While the workspace is shared, the same plan applies org config, so allowing a plan to proceed against config known to be invalid would be the worse failure. Making the step conditional on diff scope would add machinery the workspace split then deletes. The coupling goes away with the split, not before it.

Rollout / follow-ups

• The config repo needs a PROTECTED_OWNERS variable and protected_owners: ${{ vars.PROTECTED_OWNERS }} on the tf-plan caller for enforcement to take effect. Note that setting it before the org config is bootstrapped will fail every PR, correctly — it is effectively the "org management adopted" switch.
• The config repo also needs an import-org caller workflow; there is currently no way to trigger the bootstrap importer from it.
• Separate workspace/state, the other half of #1391, is a follow-up PR — it needs a new HCP workspace and config-repo wiring.
• Staged repository configs remain unvalidated. main.tf merges importer_tmp_dir/*.yaml into the applied set, but globRepoConfigs only globs repos/. This PR closes that gap for org and leaves it open for repos — same class of bug, pre-existing, and worth its own change since it can make a currently-passing import PR start failing.

[pavlovic-ivan]

LGTM