Skip to main content

Integrating Keeptrusts into CI/CD Pipelines

Integrating Keeptrusts into CI/CD is less about adding another quality gate and more about making governance changes behave like every other production change. When a policy pack lives in Git, is validated before merge, is exercised with repeatable tests, and is promoted with the same discipline as application code, teams stop treating governance as an exception path. That is where the Keeptrusts CLI is most useful: it turns policy rollout from a console-only activity into something a delivery pipeline can prove.

Use this page when​

  • You want every change to policy-config.yaml to be linted and behavior-tested before merge.
  • You need a non-interactive deployment path for approved policy changes.
  • You want post-deploy verification that a gateway is healthy and reporting events.

Primary audience​

  • Primary: Technical Engineers and platform operators
  • Secondary: Technical Leaders responsible for release controls

The problem​

Many teams adopt AI governance after they already have mature delivery pipelines for code, infrastructure, and secrets. The awkward part is that policy changes often get handled outside that machinery. A reviewer approves a YAML change in Git, but the real rollout still happens manually. A team tests a config locally, but nothing guarantees that the same file reached the production gateway. An operator knows a policy changed, but not whether the deployed version was the one that actually passed validation.

That gap creates two operational risks.

The first is drift. The file in Git says one thing and the running gateway says another. In an incident, that costs time because the team has to re-establish what is supposed to be true before they can debug what is actually happening.

The second is weak release evidence. A change request that says "the policy was tested" is much less defensible than one that can point to a pipeline run with kt policy lint, kt policy test --json, a deployment step, and a post-deploy verification step that confirms decision events are flowing.

Keeptrusts does not need a separate governance release process. It fits best when policy rollout becomes one more stage in the pipeline you already trust.

The solution​

The Keeptrusts CLI gives you the right sequence for pipeline automation:

  1. Authenticate the runner with a scoped token.
  2. Validate the config structurally with kt policy lint.
  3. validate behavior with kt policy test --json.
  4. Push or deploy the approved config with kt policy push or kt policy deploy.
  5. Verify runtime health with kt doctor, the gateway /health endpoint, and a short kt events tail query.

That sequence is important because each step proves a different thing.

Linting proves that the configuration is structurally valid. Policy tests prove the behavior you care about. Push and deploy make the change real. Post-deploy verification proves the change landed on a healthy runtime and is producing evidence in the event stream.

The other important part is authentication. CI should not use an interactive session. Keeptrusts supports scoped API tokens, so you can mint a pipeline-specific token once and inject it through your secret store. That keeps the pipeline non-interactive and auditable.

Implementation​

The cleanest pattern is to split the pipeline into three stages: validate, deploy, verify.

Outside the pipeline, create a scoped token that can perform the deployment action:

kt auth token create --name ci-governance --scope team --role-id role_configurations_writer

In the pipeline itself, run validation before any rollout step:

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

If you use GitHub Actions, the core job can stay very small:

name: keeptrusts-policy-release

on:
  push:
    branches: [main]
    paths:
      - 'policy-config.yaml'

jobs:
  release:
    runs-on: ubuntu-latest
    env:
      KEEPTRUSTS_API_URL: ${{ vars.KEEPTRUSTS_API_URL }}
      KEEPTRUSTS_API_TOKEN: ${{ secrets.KEEPTRUSTS_API_TOKEN }}
    steps:
      - uses: actions/checkout@v4

      - name: Install kt
        run: |
          curl -fsSLO https://dl.keeptrusts.com/releases/latest/kt-linux-x86_64.tar.gz
          tar xzf kt-linux-x86_64.tar.gz
          install -m 0755 kt "$HOME/.keeptrusts/bin/kt"
          echo "$HOME/.keeptrusts/bin" >> "$GITHUB_PATH"
          rm kt-linux-x86_64.tar.gz kt

      - name: Validate policy config
        run: |
          kt policy lint --file policy-config.yaml
          kt policy test --json

      - name: Push approved config
        run: |
          kt policy push --file policy-config.yaml --gateway-id staging
          kt policy deploy \
            --file policy-config.yaml \
            --source-gateway-id staging \
            --target-gateway-id production

      - name: Verify health and recent events
        run: |
          kt doctor --json
          curl -fsS http://localhost:41002/health
          kt events tail --since 5m --limit 10 --json

You do not need to overcomplicate the verification stage. A short kt events tail --since 5m --limit 10 --json query is usually enough to prove that the new version is live and still reporting decisions into the control plane. If the gateway is central rather than local to the runner, query the deployed endpoint and the control-plane events API from the same stage.

For teams using staged promotion, kt policy deploy is the most useful boundary. It lets you keep staging as the source of truth for a known-good config before rolling that same content to production gateways. That reduces the chance of accidental divergence between environments.

One practical pattern is to treat policy deployment like a canary. Push to a staging gateway, send a fixed test request through the gateway, inspect the newest events, and only then deploy to the larger target fleet. Keeptrusts supports this model well because the event trail is immediate enough to act as post-deploy evidence instead of an after-the-fact report.

Results and impact​

Teams that move Keeptrusts into CI/CD usually see two immediate improvements.

The first is release confidence. A policy change is no longer "someone updated the config." It becomes a pipeline run with explicit validation and a verifiable rollout record.

The second is faster rollback and troubleshooting. When something changes unexpectedly, the team can answer three questions quickly: what file changed, which pipeline promoted it, and what the event stream showed immediately afterward. That shortens the time from alert to root cause.

There is also a governance benefit. Audit conversations get easier when policy enforcement changes are demonstrably reviewed, tested, and promoted through controlled automation. The pipeline itself becomes part of the compliance story.

Key takeaways​

  • Keeptrusts fits naturally into CI/CD when policy configs are treated as code.
  • Use scoped tokens for automation instead of interactive login.
  • Separate the pipeline into validation, deployment, and verification stages.
  • kt policy lint, kt policy test --json, kt policy push, and kt policy deploy cover the core release path.
  • A short kt events tail query after deployment gives you real operational evidence, not just a successful job status.

Next steps​