deployment-policies/docs/tech-stack.md

Tech Stack

Overview

Layer	Technology	Version	Purpose
Policy language	Rego	OPA 1.x (rego.v1)	Authoring deployment-gateway policy rules and gates
Policy engine	OPA	v1.20.2 (pinned)	Evaluating, testing, type-checking and bundling the policies
Policy linter	regal	v0.42.0	Static linting of Rego best practices (optional in CI)
Bundles	OPA bundle format	—	Distributable .tar.gz bundles (rule modules at data.rules.*)
Schemas	JSON Schema (draft 2020-12)	—	Static validation of input and data via opa check --schema
Versioning	Changesets	@changesets/cli@3.0.3	Tracking per-policy version bumps across npm workspaces
Changelog formatting	oxfmt	^0.68.0	Formatting generated changelogs/changesets via format: "oxfmt"
Package management	npm workspaces	npm 11 / Node 24	Monorepo layout (policies/rules/*, policies/gates/*)
CI/CD	Gitea Actions	Gitea 1.27.0	Verify, test, build and publish on main
Package registry	Gitea generic registry	—	Storing published rule/gate bundles
Build tooling	GNU make + bash	—	Makefile targets wrapping the scripts
Hosting	Gitea self-hosted	1.27.0	Source control, CI runners, package registry (gitea.devegamoreno.com)

Justification

• OPA + Rego: standard, policy-as-code engine for authorization/gating; bundles are the portable distribution unit; binary CLI avoids container runtime requirements.
• Pinned OPA v1.20.2: reproducible engine version locally and in CI via scripts/install-opa.sh (no Docker), so tests and opa build see identical behaviour everywhere.
• rego.v1: canonical OPA 1.x syntax (import of rego.v1), future-proof and unambiguous.
• Per-rule JSON Schemas: opa check --strict --schema catches input/data type mistakes at authoring time instead of runtime.
• Separate evaluation / small rules: each rule is an independent package+bundle with a small, testable contract; consumers combine the results at runtime, enabling reuse across gates.
• Changesets over npm workspaces: each rule/gate is an npm package solely for versioning; changesets links repository-level changes to published registry versions. oxfmt is used only to format changelog markdown (there is no prettier-plugin-rego on npm), while Rego formatting is enforced by opa fmt in CI.
• Gitea generic registry: stores arbitrary files (.tar.gz bundles) under /api/packages/{owner}/generic/{package}/{version}/{file} without adding an external registry dependency.
• npm workspaces (over pnpm/yarn): zero extra tooling; changesets v3 requires Node ≥ 22.11 and npm ≥ 10.9, both met.

Tools not used (and why)

• Docker/containers: excluded by design; OPA ships a static binary, so containers add unnecessary runtime complexity for tests, checks and bundle builds.
• prettier-plugin-rego: does not exist on npm (verified 404); Rego formatting is instead owned by opa fmt.
• pnpm/yarn: changesets supports them, but npm workspaces suffice since these packages are private versioning shims, not published JS packages.

Integration points

• Gitea Actions reads secrets.GITEA_TOKEN (scope write:package) and GITEA_OWNER/GITEA_URL; publish job runs only on main.
• scripts/publish.sh uploads via curl to the generic registry; package names are prefixed rule-* and gate-*.
• Consumer contract: bundles scope roots to rules so operators can supply data.deploygate.* configuration separately and still have static schema checks apply.

Environment (local dev machine)

• macOS (darwin/arm64), zsh
• Node.js v24.18.0, npm 11.16.0
• git 2.50.1, GNU make
• tools/opa (OPA v1.20.2 binary committed to the repo working tree via install script, not git)
• regal v0.42.0 optional on PATH