Environment Promotion

Promote policies from development to staging to production using al export and al import. Policies are stored as YAML files in git — the same diff and review workflow your team already uses for code changes.

How It Works

Each environment is a separate AgentLattice workspace with its own API keys, policies, and audit log. You export policies from one workspace, review the file in git, then import it into another workspace.

dev workspace    staging workspace    production workspace
─────────────    ─────────────────    ────────────────────
al export    →   al import        al import
  ↓                ↓                ↓
policies.yaml    (review)         (review + gate)

The YAML file is the source of truth. Checking it into git gives you history, rollback, and code review for policy changes.

Quick Start

Step 1: Export policies from dev

export AL_SERVICE_KEY="al_svc_dev_key_here"
al export --file policies/dev.yaml

Step 2: Preview what will change in staging

export AL_SERVICE_KEY="al_svc_staging_key_here"
al import --file policies/dev.yaml --dry-run

Output:

DRY RUN — no changes will be written
Preview — no changes applied:
  + 1 added:
      block-unreviewed-deploys
  ~ 1 modified:
      audit-all-writes
  = 3 unchanged

Step 3: Apply to staging

al import --file policies/dev.yaml

Service Keys

Export and import require a service key, not an agent API key. This is intentional — an agent must not be able to overwrite the governance rules that govern its own behavior.

Get your service key from the AgentLattice dashboard under Settings → Service Keys.

Each environment org has its own service key:

# Dev
export AL_SERVICE_KEY="al_svc_dev_..."

# Staging
export AL_SERVICE_KEY="al_svc_staging_..."

# Production
export AL_SERVICE_KEY="al_svc_prod_..."

GitOps Workflow

The recommended pattern is to store policy manifests in git and use CI/CD to promote them automatically.

Directory structure:

policies/
  dev.yaml
  staging.yaml
  production.yaml

GitHub Actions example:

name: Promote policies to staging

on:
  push:
    paths:
      - policies/staging.yaml
    branches:
      - main

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

      - name: Preview changes
        env:
          AL_SERVICE_KEY: ${{ secrets.AL_STAGING_SERVICE_KEY }}
        run: |
          npx @agentlattice/cli import \
            --file policies/staging.yaml \
            --dry-run

      - name: Apply policies
        env:
          AL_SERVICE_KEY: ${{ secrets.AL_STAGING_SERVICE_KEY }}
        run: |
          npx @agentlattice/cli import \
            --file policies/staging.yaml

Replace Mode

By default, al import is additive: policies in the manifest are created or updated, but policies already in the org that are not in the manifest are left alone.

Use --replace for a full sync — policies absent from the manifest are deactivated:

al import --file policies/staging.yaml --replace

Use --replace when you want the org's policy set to exactly match the manifest file, with no leftover policies from previous configurations.

Manifest Format

The manifest is a YAML file with a predictable structure:

manifest_version: '1.0'
exported_at: '2026-04-01T10:30:00.000Z'
org_name: My Org (dev)
policies:
  - name: block-unreviewed-deploys
    action_type: deploy.production
    approval_required: true
    approval_timeout_hours: 24
    allowed_repos: null
    allowed_branches: null
    conditions: |
      logic: all
      rules:
        - field: branch
          operator: regex
          value: "^main$"
  - name: audit-all-writes
    action_type: db.write
    approval_required: false
    approval_timeout_hours: 8
    allowed_repos: null
    allowed_branches: null
    conditions: null
circuit_breakers_info:
  note: Circuit breakers are exported for reference only. They are not applied on al import.
  entries:
    - anomaly_type: rapid_tool_invocation
      score_threshold: 70
      response_level: HALT

Policy identity: Policies are matched by name when importing. Renaming a policy in the manifest creates a new policy and leaves the old one unchanged (unless you use --replace). Use names that are stable across environments.

Audit Trail

Every successful import writes a tamper-proof audit event to the workspace's audit log:

• What changed (added, modified, deleted counts)
• The full manifest hash (SHA-256)
• The manifest version
• Whether replace mode was used

This gives security teams a complete history of policy changes across all environments.

Troubleshooting

UNSUPPORTED_MANIFEST_VERSION — The manifest was exported with a newer version of the CLI. Run al export again with the current CLI version.

POLICY_COMPILE_ERROR — A policy's conditions field contains invalid YAML or an unknown operator. Check the error message for which policy failed and fix the conditions syntax.

INVALID_SERVICE_KEY — The AL_SERVICE_KEY environment variable is missing or the key doesn't match the target org. Verify you're using the right key for the right environment.