CI/CD integration

AI coding agents running in CI/CD pipelines — Claude Code, Copilot, Cursor — carry the same risks as local development but with less human oversight. A compromised or misconfigured agent in a pipeline can modify workflow files, exfiltrate secrets, or disable governance tooling entirely.

Vectimus ensures the same Cedar policies that protect local development apply in automated pipelines. Every tool call is evaluated, every decision is logged, and tamper-evident receipts are generated for audit.

Quick start with GitHub Actions

Add two lines to any job that runs an AI coding agent:

- name: Install and initialise Vectimus
  run: |
    pip install vectimus
    vectimus init --ci

The --ci flag

vectimus init --ci configures Vectimus for non-interactive environments:

• Suppresses all interactive prompts (no TTY required)
• Discovers MCP servers in the project but does not allow them unless --allow-mcp is also passed
• Sets identity_type = "agent" automatically
• Writes config and hooks to the project .vectimus/ directory

To allow discovered MCP servers:

- name: Install and initialise Vectimus
  run: |
    pip install vectimus
    vectimus init --ci --allow-mcp

Which policies apply

The same policy packs used locally apply in CI. Vectimus ships bundled policies and syncs updates from api.vectimus.com via vectimus policy update. No separate CI-specific configuration is needed.

Key policies for CI/CD

These policies are active by default in the bundled policy packs. No opt-in required.

Audit trail artifacts

Vectimus writes tamper-evident receipts and logs during execution. Upload them as pipeline artifacts so they survive after the runner is destroyed.

- name: Upload vectimus audit trail
  if: always()
  uses: actions/upload-artifact@v7
  with:
    name: vectimus-audit-${{ github.job }}-${{ github.run_id }}
    path: |
      .vectimus/receipts/
      .vectimus/keys/
      ~/.vectimus/logs/
    retention-days: 90
    if-no-files-found: ignore

The if: always() ensures artifacts are uploaded even when previous steps fail — this is when audit logs matter most.

What each directory contains

• .vectimus/receipts/ — Signed JSON receipts for every policy evaluation. Each receipt includes the tool call, the policy decision, and a cryptographic signature.
• .vectimus/keys/ — Public keys used to verify receipt signatures. Store these alongside receipts for independent verification.
• ~/.vectimus/logs/ — Detailed evaluation logs including Cedar policy traces.

Full example

A complete GitHub Actions job running Vectimus with the Claude Code action:

name: AI agent task
on:
  issues:
    types: [opened, labeled]

permissions:
  contents: write
  pull-requests: write
  issues: write

jobs:
  agent-task:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683

      - name: Install and initialise Vectimus
        run: |
          pip install vectimus
          vectimus init --ci

      - name: Run Claude Code
        uses: anthropics/claude-code-action@v1.0.77
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

      - name: Upload vectimus audit trail
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: vectimus-audit-${{ github.job }}-${{ github.run_id }}
          path: |
            .vectimus/receipts/
            .vectimus/keys/
            ~/.vectimus/logs/
          retention-days: 90
          if-no-files-found: ignore

CI/CD security checklist

These GitHub Actions best practices complement Vectimus governance. Vectimus enforces policy on agent behaviour; these practices harden the pipeline itself.

• Pin all third-party actions to a specific SHA, not a mutable tag like @v1 or @master. Mutable tags can be moved to point at malicious code.
• Declare explicit permissions: blocks on every workflow. Never rely on the repository default. Scope each permission to the minimum required (contents: read, not contents: write, unless writes are needed).
• Never use --dangerously-skip-permissions in CI. This flag disables all Vectimus policy evaluation. It exists for local debugging only.
• Use pull_request, not pull_request_target, for PR workflows. pull_request_target runs with the base branch’s secrets and write access, which external contributors can exploit.
• Scope tokens to minimum required permissions. Use fine-grained personal access tokens over classic tokens. Limit repository and permission scope.
• Review Dependabot alerts regularly. Vulnerable dependencies in the pipeline are a supply chain risk that governance policies cannot catch.

Environment variables

Set these environment variables in your workflow to configure Vectimus identity in CI.

Example usage in a workflow:

env:
  VECTIMUS_GROUPS: ci,deploy
  VECTIMUS_IDENTITY_TYPE: agent

These variables take precedence over values in .vectimus/config.toml and ~/.vectimus/config.toml. See the Configuration Reference for the full resolution order.