Integrate Keeptrusts into CI/CD Pipelines

Embedding Keeptrusts into your CI/CD pipeline ensures every change to AI governance policy is validated before it reaches production. This guide covers pipeline integration for GitHub Actions, GitLab CI, and Jenkins.

Use this page when

• You want to add policy validation gates to existing CI/CD pipelines (GitHub Actions, GitLab CI, or Jenkins).
• You need to automate kt policy lint and kt gateway run --dry-run on every pull request.
• You are setting up automated config deployment to staging and production gateways.
• You need ephemeral test gateways per PR for integration testing.

Primary audience

• Primary: Technical Engineers
• Secondary: AI Agents, Technical Leaders

Architecture overview

Developer pushes policy YAML
  → CI pipeline triggers
    → kt policy lint (syntax + schema check)
    → kt gateway run --dry-run (policy simulation)
    → Deploy to staging gateway
    → Smoke test with kt events tail
    → Promote to production

The pipeline validates policy files, runs a test gateway, and only promotes configs that pass all checks.

Prerequisites

• Keeptrusts CLI (kt) installed in your CI runner image
• API key stored as a CI secret (KEEPTRUSTS_API_TOKEN)
• A policy config repository (YAML files under config/)

GitHub Actions

Validate on pull request

Create .github/workflows/keeptrusts-validate.yml:

name: Validate AI Governance Config
on:
  pull_request:
    paths:
      - 'config/**/*.yaml'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Keeptrusts CLI
        run: |
          curl -sSL https://install.keeptrusts.com | sh
          echo "$HOME/.keeptrusts/bin" >> $GITHUB_PATH

      - name: Validate policy config
        run: kt policy lint --file config/policy-config.yaml

      - name: Dry-run gateway
        env:
          KEEPTRUSTS_API_TOKEN: ${{ secrets.KEEPTRUSTS_API_TOKEN }}
        run: |
          kt gateway run \
            --config config/policy-config.yaml \
            --dry-run \
            --timeout 30s

Deploy on merge to main

name: Deploy AI Governance Config
on:
  push:
    branches: [main]
    paths:
      - 'config/**/*.yaml'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Keeptrusts CLI
        run: |
          curl -sSL https://install.keeptrusts.com | sh
          echo "$HOME/.keeptrusts/bin" >> $GITHUB_PATH

      - name: Push configuration
        env:
          KEEPTRUSTS_API_TOKEN: ${{ secrets.KEEPTRUSTS_API_TOKEN }}
          KEEPTRUSTS_API_URL: ${{ vars.KEEPTRUSTS_API_URL }}
        run: |
          kt config push \
            --path config/policy-config.yaml \
            --env production

GitLab CI

Add to .gitlab-ci.yml:

stages:
  - validate
  - deploy

variables:
  KT_VERSION: "latest"

validate-policy:
  stage: validate
  image: ubuntu:22.04
  rules:
    - changes:
        - config/**/*.yaml
  script:
    - curl -sSL https://install.keeptrusts.com | sh
    - export PATH="$HOME/.keeptrusts/bin:$PATH"
    - kt policy lint --file config/policy-config.yaml
    - kt gateway run --policy-config config/policy-config.yaml --dry-run --timeout 30s

deploy-policy:
  stage: deploy
  image: ubuntu:22.04
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      changes:
        - config/**/*.yaml
  script:
    - curl -sSL https://install.keeptrusts.com | sh
    - export PATH="$HOME/.keeptrusts/bin:$PATH"
    - kt config push --path config/policy-config.yaml --env production

Jenkins

Jenkinsfile

pipeline {
    agent any

    environment {
        KEEPTRUSTS_API_TOKEN = credentials('keeptrusts-api-key')
        KEEPTRUSTS_API_URL = 'https://api.keeptrusts.com'
    }

    stages {
        stage('Validate') {
            when {
                changeset 'config/**/*.yaml'
            }
            steps {
                sh 'curl -sSL https://install.keeptrusts.com | sh'
                sh '$HOME/.keeptrusts/bin/kt policy lint --file config/policy-config.yaml'
            }
        }

        stage('Test Gateway') {
            steps {
                sh '''
                    $HOME/.keeptrusts/bin/kt gateway run \
                      --config config/policy-config.yaml \
                      --dry-run \
                      --timeout 30s
                '''
            }
        }

        stage('Deploy') {
            when {
                branch 'main'
            }
            steps {
                sh '''
                    $HOME/.keeptrusts/bin/kt config push \
                      --path config/policy-config.yaml \
                      --env production
                '''
            }
        }
    }
}

Smoke testing in the pipeline

After deploying a config, verify the gateway is enforcing policy:

# Tail events to confirm the gateway is active
kt events tail --limit 5 --format json

# Verify specific policy enforcement
curl -s http://gateway:41002/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"test prompt"}]}' \
  | jq '.choices[0].message.content'

Test environment gateways

Spin up an ephemeral gateway per PR for integration testing:

# GitHub Actions — ephemeral test gateway
- name: Start test gateway
  run: |
    kt gateway run \
      --config config/policy-config.yaml \
      --port 0 \
      --pid-file /tmp/kt-gateway.pid &
    sleep 5
    GATEWAY_PORT=$(kt gateway status --pid-file /tmp/kt-gateway.pid --format json | jq -r '.port')
    echo "GATEWAY_URL=http://localhost:$GATEWAY_PORT" >> $GITHUB_ENV

- name: Run integration tests
  run: npm test -- --gateway-url $GATEWAY_URL

- name: Stop test gateway
  if: always()
  run: kill $(cat /tmp/kt-gateway.pid) || true

Secrets management

CI Platform	Secret Storage	Usage
GitHub Actions	Repository secrets	${{ secrets.KEEPTRUSTS_API_TOKEN }}
GitLab CI	CI/CD variables (masked)	$KEEPTRUSTS_API_TOKEN
Jenkins	Credentials plugin	credentials('keeptrusts-api-key')

Never hardcode API keys in pipeline files. Use your CI platform's native secrets management.

Troubleshooting

Issue	Cause	Fix
kt policy lint fails with schema error	YAML does not match expected policy schema	Review the reported field path, fix the YAML, then rerun the lint step
Gateway dry-run timeout	Config references unavailable upstream provider	Set --timeout higher or mock the provider in CI
Deploy returns 401	API key missing or expired	Rotate the key in your CI secrets store
Events not appearing after deploy	Gateway not reloaded	Use kt config push which triggers automatic reload

For AI systems

• Canonical terms: Keeptrusts CLI, kt policy lint, kt gateway run --dry-run, kt config push, policy validation, gateway dry-run, CI/CD pipeline.
• Key config: KEEPTRUSTS_API_TOKEN (CI secret), KEEPTRUSTS_API_URL, config/policy-config.yaml path triggers.
• Supported CI platforms: GitHub Actions, GitLab CI, Jenkins.
• Best next pages: GitHub Actions, GitLab CI, Webhook-driven workflows.

For engineers

• Prerequisites: kt CLI available in CI runner, KEEPTRUSTS_API_TOKEN stored as a masked CI secret, policy YAML files in a Git repository.
• Validate: kt policy lint --file config/policy-config.yaml (exits non-zero on schema errors), kt events tail --limit 5 after deploy.
• Secrets: Never hardcode API keys — use GitHub secrets, GitLab masked variables, or Jenkins credentials plugin.
• Ephemeral gateways: Start CI gateways with an explicit listen address such as kt gateway run --listen 127.0.0.1:41002 --policy-config config/policy-config.yaml; if jobs run in parallel on the same host, assign distinct ports per job in the workflow.

For leaders

• Risk reduction: Automated policy validation prevents misconfigurations from reaching production. Every policy change is tested before merge.
• Audit trail: CI logs provide a timestamped record of who approved and deployed each governance config change.
• Rollback: Git-based configs allow instant rollback via git revert + pipeline re-deploy.
• Team workflow: Require PR reviews from compliance team members before policy changes merge to main.

Next steps

• Set up Slack & Teams alerts for deployment notifications
• Deploy on Kubernetes for production-grade hosting
• Feed events to your SIEM for audit trail compliance