# gator test: Test Gatekeeper Constraints Offline

> gator test evaluates OPA Gatekeeper ConstraintTemplates and Constraints against resources without a cluster. Reference for stdin input, --output, and the violation output in CI.

Source: https://latchkey.dev/learn/command-reference/gator-test  
Updated: 2026-06-30

gator test runs Gatekeeper ConstraintTemplates and Constraints against Kubernetes resources locally, printing any violations and exiting non-zero when they occur.

If your cluster enforces policy with OPA Gatekeeper, gator test lets you run those exact ConstraintTemplates and Constraints in CI. A manifest that Gatekeeper would reject at admission fails the PR instead.

## What it does

gator test reads a stream of Kubernetes objects (ConstraintTemplates, Constraints, and the resources to check) from stdin or files, compiles the templates, and evaluates the constraints. It reports each violation with the constraint name and message and exits non-zero if any resource is denied.

## Common usage

```Terminal
# feed templates, constraints, and resources together
cat template.yaml constraint.yaml deployment.yaml | gator test
# from a directory (via find/cat) with JSON output
cat policy/*.yaml manifests/*.yaml | gator test --output json
# explicit filenames
gator test -f template.yaml -f constraint.yaml -f deployment.yaml
```

## Options

| Flag | What it does |
| --- | --- |
| -f, --filename <path> | Input file or directory; repeatable |
| stdin | Read a YAML stream of objects when no -f is given |
| -o, --output <fmt> | Output format: default (yaml-ish), json |
| --include-trace | Include Rego evaluation trace for debugging |
| --image <ref> | Pull a bundle of policies from an OCI image |

## In CI

Vendor the same ConstraintTemplates and Constraints your cluster applies, concatenate them with the manifests under review, and pipe into gator test. Because it runs the identical Rego Gatekeeper uses, local and admission verdicts match, closing the gap where a PR passes CI but fails at deploy.

## Common errors in CI

A denied resource prints a violation line such as "Deployment <name>: <constraint message>" (for example "you must provide labels: {app.kubernetes.io/name}") and the process exits non-zero. "error creating client" or "no ConstraintTemplate found" means you forgot to include the template in the input stream. A Rego compile error surfaces as "failed to create template" with the underlying rego_parse_error.

## Using this in CI

A runner has no kubeconfig, no cached context, and no interactive auth. Every kubectl invocation in CI needs the context supplied explicitly, and most confusing CI failures here are the command running against the wrong cluster or no cluster at all.

```Terminal
# never rely on the ambient context on a runner
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" get pods

# confirm what you are actually connected to before mutating anything
kubectl config current-context
kubectl cluster-info

# fail fast instead of hanging on an unreachable API server
kubectl --request-timeout=30s get nodes
```

> Always set `--request-timeout` in CI. Without it an unreachable API server hangs until the job times out, which turns a thirty-second failure into a twenty-minute one.

## FAQ

### gator test: Test Gatekeeper Constraints Offline?

If your cluster enforces policy with OPA Gatekeeper, gator test lets you run those exact ConstraintTemplates and Constraints in CI. A manifest that Gatekeeper would reject at admission fails the PR instead.

### What it does?

gator test reads a stream of Kubernetes objects (ConstraintTemplates, Constraints, and the resources to check) from stdin or files, compiles the templates, and evaluates the constraints. It reports each violation with the constraint name and message and exits non-zero if any resource is denied.

### In CI?

Vendor the same ConstraintTemplates and Constraints your cluster applies, concatenate them with the manifests under review, and pipe into gator test. Because it runs the identical Rego Gatekeeper uses, local and admission verdicts match, closing the gap where a PR passes CI but fails at deploy.

### Common errors in CI?

A denied resource prints a violation line such as "Deployment <name>: <constraint message>" (for example "you must provide labels: {app.kubernetes.io/name}") and the process exits non-zero. "error creating client" or "no ConstraintTemplate found" means you forgot to include the template in the input stream.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt