Fleet Ops: manage the schema as Terraform, with CI for a policy repository

[Zivxx]

Stacked on #10. Adds the policy-as-code half of the Fleet Ops example: the same schema make setup writes through the API, as Terraform, plus the CI a policy repository needs to plan and apply it per environment.

What's in it

• fleet-ops-demo/gitops/ is laid out like the repository Permit's GitOps reads, so it can be copied as is:
  • terraform/: the schema with the permitio/permit-io provider (0.0.26). It holds the same objects as internal/schema/schema.go: resource types, roles, relations, derivations, the two resource sets and their rules. cloud.tf keeps the state in HCP Terraform; delete it to keep the state locally.
  • .github/workflows/terraform.yaml:
    • on a pull request: format, validate, plan, and the plan posted as a comment;
    • on a push: main applies to Development and release/* to Production.
  • .github/workflows/policy-tests.yaml: opa check and opa test for the custom rules.
  • ci/permit_snapshot.py (standard library only): Permit deletes a role's assignments when the role is deleted, and a relation's tuples when the relation is deleted. Before each apply, this script saves what the plan deletes. When a revert is applied, it puts that data back. The README says plainly that this is the example's own code, not a Permit or Terraform feature, and lists its limits.
• These workflows are templates. GitHub only runs workflows at the repository root, so nothing new runs in this repo.
• This example's own CI gets a terraform job: terraform fmt -check, plus init -backend=false and validate, which need no credentials. It also compiles the snapshot script.
• Also added: a terraform fmt pre-commit hook, a Dependabot entry for the provider, and a "Policy as code" paragraph and layout row in the example's README.

Review

The change went through the pr-pipeline. Both Python verifiers (idioms, risk) reviewed the snapshot script and the workflow that drives it, then pr-fixer adjudicated all 19 findings. Every finding was fixed, documented in gitops/README.md, or declined with a reason. The main ones:

• Blocker, fixed: the restore step looked a snapshot up by artifact name. A fork's pull request could upload an artifact under that name, and it would be unzipped over the checkout and run with the production key in the environment. Now:

  • only this workflow's push runs on the branch are trusted;
  • the snapshot comes from the run that applied the reverted commit;
  • it's downloaded into $RUNNER_TEMP and read as data only.

• Fixed:

  • retries on 5xx responses and network errors, honouring Retry-After;
  • bulk posts sent at most 1000 at a time, falling back to one item at a time when Permit refuses a batch;
  • pipefail, so a failed plan can't post an empty one;
  • concurrency grouped per environment, not per branch;
  • the log shows counts, never user keys;
  • save stops the apply when the plan deletes a resource type that still has instances, since no snapshot can bring those back.

• Documented, not built:

  • reverting a commit from the middle of a push;
  • snapshots expiring after 30 days;
  • squash-merge settings that drop the "This reverts commit" line;
  • restore giving back access that was removed on purpose since the snapshot;
  • using one release branch at a time.

  Each of these makes the apply fail with an explanation, and the README says how to restore by hand.

One follow-up I made after the fixer (fa878a1): the revert search now starts from the last successful apply. Before, a revert whose run failed before applying would never be restored.

Tests

• terraform fmt -check and validate (Terraform 1.13.5). The schema files are byte-identical to the baseline that was checked object by object against an environment created by make setup; schema.go has changed since only in comments.
• actionlint with shellcheck, and zizmor, on all three workflows; pre-commit (gitleaks, typos, zizmor); py_compile.
• The snapshot script against a local mock of Permit's facts API, built from reading the backend: matching by role and type, paging, replacements, chunking past 1000, refusals, an unknown environment, retries and timeouts. Permit's real API was not called.
• The restore step, extracted verbatim from terraform.yaml, run through 14 scenarios with real git history and a gh stub: fork artifacts, a script inside an artifact, mid-push reverts, cancelled and failed runs, expired and missing snapshots, re-run attempts, rewritten history. Nothing ran on GitHub itself. The gh calls were checked against the stub and the docs only.

Names

The only organizations named are the example's made-up ones: Fleet Ops, Acme Freight, Lone Star Logistics, Summit Freight Group, Mesa Fleet Services and Freightline.

🤖 Generated with Claude Code