Validate & Lint AI Policies Before Deployment

Keeptrusts treats declarative config as a contract. The safest workflow is:

Use this page when

• You need to validate a policy-config.yaml before deploying it to a running gateway.
• You want to add kt policy lint and kt policy test to a CI pipeline (GitHub Actions, GitLab CI).
• You are troubleshooting a lint failure or need to understand what each check covers.

Edit policy-config.yaml → kt policy lint → kt policy test --json → run or deploy

Use linting to catch schema and wiring mistakes, then use tests to prove the behavior you expect before a gateway ever serves traffic.

Primary audience

• Primary: Technical Engineers authoring or reviewing policy configurations
• Secondary: CI/CD pipeline owners, AI Agents generating configs programmatically

kt policy lint

kt policy lint validates a config file directly:

kt policy lint --file policy-config.yaml

What it checks

Check	What it protects against
YAML syntax	Broken indentation, duplicate keys, malformed documents
Top-level shape	Missing or invalid pack, providers, policies, or policy sections
Supported policy names	Unknown controls in policies.chain
Policy configuration blocks	Missing required fields or unsupported fields in policy.<name>
Provider target wiring	Invalid provider targets, bad routing references, or unresolved target ids

Example failure

$ kt policy lint --file policy-config.yaml

policy.pii-detector.action: expected one of [redact, block]
providers.targets[0].id: duplicate target id "openai-primary"
policy lint failed (2 error(s))

kt policy test

kt policy test runs the pack tests that live beside your config. kt init creates a starter tests/ directory so you have a place to codify expected policy behavior from day one.

kt policy test --json

If your pack lives somewhere else, point the runner at that directory:

kt policy test --json --pack-dir ./policies/customer-support

What tests should cover

1. Requests that should be blocked.
2. Requests that should be redacted.
3. Requests that should pass unchanged.
4. Any routing or provider behavior your production config depends on.

Example output

{
  "ok": true,
  "results": [
    { "name": "blocks_prompt_injection", "ok": true },
    { "name": "redacts_pii_before_upstream", "ok": true }
  ]
}

Recommended working loop

kt policy lint --file policy-config.yaml
kt policy test --json
kt gateway run --policy-config policy-config.yaml

If you manage rollout from the console or Git Integration instead of a local gateway, keep the first two commands in CI and deploy only after both are green.

CI integration

GitHub Actions

name: Policy Validation
on:
  pull_request:
    paths:
      - 'policy-config.yaml'
      - 'tests/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install kt
        run: curl -fsSL https://get.keeptrusts.com | sh
      - name: Lint config
        run: kt policy lint --file policy-config.yaml
      - name: Run policy tests
        run: kt policy test --json

GitLab CI

policy-validation:
  stage: validate
  image: keeptrusts/cli:latest
  script:
    - kt policy lint --file policy-config.yaml
    - kt policy test --json

Business outcomes

Outcome	How validation helps
Safer rollouts	Broken YAML or unsupported config never reaches a running gateway
Fewer regressions	Pack tests preserve the behavior you expect as policies evolve
Faster reviews	Teams can review config diffs and test output together in pull requests
Better auditability	The config and its test suite become the evidence trail for why a change was safe to deploy

For AI systems

• Canonical terms: kt policy lint, kt policy test, policy-config.yaml, pack tests, YAML schema validation, provider target wiring.
• Commands: kt policy lint --file <path>, kt policy test --json, kt policy test --json --pack-dir <dir>.
• Checks performed: YAML syntax, top-level shape, supported policy names, policy configuration blocks, provider target wiring.
• Best next pages: Declarative Config Patterns, Policy Chains.

For engineers

• Prerequisites: kt CLI installed, a policy-config.yaml file, and optionally a tests/ directory (generated by kt init).
• Working loop: kt policy lint --file policy-config.yaml && kt policy test --json && kt gateway run --policy-config policy-config.yaml.
• CI gate: add both commands to your PR pipeline; deploy only when both exit 0.
• Troubleshoot lint failures by reading the error output — it reports exact field paths and accepted values.

For leaders

• Lint + test in CI prevents broken or unsafe policy configs from reaching production gateways.
• Pack tests serve as living documentation of expected policy behavior — reviewable alongside code diffs.
• Reduces change-management risk: every config PR has automated proof it won’t break enforcement.
• Audit evidence: the CI log becomes a timestamped record that the config was validated before deployment.

Next steps

• Declarative Config Patterns — organize larger config packs without losing clarity
• kt policy lint — command reference
• kt policy test — command reference