How-To Guides
Author, Test, and Roll Out OPA Policies
Real product workflow for creating policy sets, adding built-ins/custom Rego, assigning scopes, and verifying violations.
Task Outcome
You can safely introduce OPA governance in GitOpsHQ using the current product behavior, without relying on assumptions from other platforms.
Before You Start
- Values Governance feature is enabled for your account.
- You can open
Policiespage and seePolicy Sets,Built-ins, andViolationssurfaces. - You know which scope to govern first (
projectorenvironmentis recommended).
UI Route Map
- Open
Policiespage. - Create a
Policy Set. - Add built-ins and/or custom Rego policies.
- Add assignments.
- Run
Playgroundtests. - Observe
Violationsand tune.
Step-By-Step Execution
Create a new policy set with clear scope intent (for example
Production Values Guardrails).Add 1-2 built-in policies first to avoid broad initial blast radius.
Add assignment at narrow scope (
project or specific environment) before organization-wide rollout.Use preview drawer to inspect the actual Rego content of each built-in.
Open Playground, load built-in Rego, and test with real-like YAML input.
Add a custom Rego policy if built-ins do not cover your requirement.
Validate violation behavior from real workflow actions (values update / promotion path).
Tune or remove noisy rules, then expand assignment scope gradually.
Built-in First Strategy
- Start with one set and limited assignments.
- Prefer high-signal rules over large bundles.
- Security basics: no privileged, no host network, no latest tag.
- Reliability basics: resource limits and min replicas in production.
- Large access-control bundles if your team context is still unstable.
- Wide organization-level assignments on day one.
- After stable behavior, add more categories and wider scopes.
- Review unresolved violations trend before each expansion.
Custom Rego Authoring Rules
- Name rules with
deny_...orwarn_...for predictable evaluation. - Return human-readable message strings in rule outputs.
- Keep conditions explicit on
input.context.environmentand value paths. - Use small rules; avoid large multi-purpose policy blocks.
Minimal custom policy starter
package gitopshq.custom
deny_missing_tls contains msg if {
not input.values.tls.enabled
msg := "TLS must be enabled"
}Assignment Playbook
- Highest blast radius.
- Use after lower-scope validation is complete.
- Best default rollout scope.
- Clear ownership and fast feedback loop.
- Good for production-only strictness.
- Supports optional project scoping in assignment dialog.
- Useful for shared standards across specific ownership groups.
- Validate target identity carefully before submit.
Validation Checklist
- Policy set is enabled.
- At least one assignment is active.
- Playground tests include pass + fail samples.
- Violations appear with understandable messages.
- Unintended blocks are tuned before scope expansion.
Troubleshooting
- No effect after creating rules: check set
enabledstate and assignment existence. - Unexpected hard block from built-in: built-in add flow currently defaults to
denyenforcement. - Empty playground output: verify
deny*/warn*rule naming and input YAML structure. - Access-control rule not triggering: verify
useranddiff.changedFieldscontext is available in that workflow.
Change Log Template
Policy set:
Change date:
Owner:
Added/updated policy:
Assignment scope:
Playground test summary:
Observed violations:
Rollback/tuning action: