> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mnemom.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CI/CD Policy Gates

> Integrate policy validation and evaluation into your CI/CD pipeline with GitHub Actions and GitLab CI

Policy gates prevent misconfigurations from reaching production. By embedding policy checks directly into your CI/CD pipeline, you catch violations before they affect live agent traffic -- not after.

There are two types of gates:

1. **Static validation** -- `mnemom card validate` checks schema correctness. It is fast, offline, and makes no API calls.
2. **Card evaluation** -- `mnemom card evaluate` checks the card's policy against a set of tools. It can run locally or against live agent data.

Both commands return CI-friendly exit codes: `0` on pass, `1` on failure. This means any CI system that interprets exit codes (GitHub Actions, GitLab CI, Jenkins, CircleCI, etc.) will correctly pass or fail the pipeline step.

***

## Static validation gate

Static validation checks that your alignment card conforms to the unified schema without making any API calls. This makes it fast, safe to run on every pull request, and suitable for environments without API credentials.

<Note>
  Static validation catches structural errors -- missing required fields, invalid enum values, malformed glob patterns, and schema version mismatches. It does not verify that capability mappings reference real tools or that coverage is adequate. Use [card evaluation](#card-evaluation-gate) for that.
</Note>

<Tabs>
  <Tab title="GitHub Actions">
    ```yaml theme={null}
    # .github/workflows/card-validate.yml
    name: Card Validation
    on:
      pull_request:
        paths:
          - 'card.yaml'
          - 'cards/**'

    jobs:
      validate-card:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - uses: actions/setup-node@v4
            with:
              node-version: '20'
          - run: npm install -g @mnemom/mnemom
          - name: Validate card
            run: mnemom card validate card.yaml
    ```

    This workflow triggers only when `card.yaml` or files under `cards/` change, keeping CI fast for unrelated pull requests.
  </Tab>

  <Tab title="GitLab CI">
    ```yaml theme={null}
    # .gitlab-ci.yml
    validate-card:
      stage: test
      image: node:20
      script:
        - npm install -g @mnemom/mnemom
        - mnemom card validate card.yaml
      only:
        changes:
          - card.yaml
          - cards/**
    ```

    GitLab's `only:changes` directive provides the same path-scoped triggering as GitHub's `paths` filter.
  </Tab>
</Tabs>

<Tip>
  Run static validation first in your pipeline. It completes in under a second and catches the most common errors before the slower evaluation step runs.
</Tip>

***

## Card evaluation gate

Card evaluation goes beyond schema validation. It evaluates your card's policy against the agent's tools -- checking capability mapping coverage, verifying tool permissions, and scoring the card against tool usage. This can run locally or with an API key for live agent data.

<Warning>
  The evaluation gate may make API calls and read live agent data when using `--agent`. Only run it in trusted CI environments where your API key is stored as a secret. Never log the full evaluation response in public build logs if it contains agent identifiers or tool names you consider sensitive.
</Warning>

<Tabs>
  <Tab title="GitHub Actions">
    ```yaml theme={null}
    # .github/workflows/card-evaluate.yml
    name: Card Evaluation
    on:
      push:
        branches: [main]

    jobs:
      evaluate-card:
        runs-on: ubuntu-latest
        env:
          MNEMOM_API_KEY: ${{ secrets.MNEMOM_API_KEY }}
        steps:
          - uses: actions/checkout@v4
          - uses: actions/setup-node@v4
            with:
              node-version: '20'
          - run: npm install -g @mnemom/mnemom
          - name: Evaluate card
            run: mnemom card evaluate card.yaml --tools mcp__browser__navigate,mcp__slack__post_message --agent my-agent --strict
    ```

    This workflow runs on pushes to `main`, making it a pre-deploy gate. The `MNEMOM_API_KEY` is read from GitHub Secrets and exposed as an environment variable.
  </Tab>

  <Tab title="GitLab CI">
    ```yaml theme={null}
    # .gitlab-ci.yml
    evaluate-card:
      stage: deploy
      image: node:20
      variables:
        MNEMOM_API_KEY: $MNEMOM_API_KEY
      script:
        - npm install -g @mnemom/mnemom
        - mnemom card evaluate card.yaml --tools mcp__browser__navigate,mcp__slack__post_message --agent my-agent
      only:
        - main
    ```

    In GitLab, store `MNEMOM_API_KEY` as a CI/CD variable (Settings > CI/CD > Variables) with the "Masked" option enabled.
  </Tab>
</Tabs>

***

## Exit codes and error handling

Both `card validate` and `card evaluate` use standard exit codes that CI systems interpret automatically:

| Exit Code | Meaning                           | CI Behavior        |
| --------- | --------------------------------- | ------------------ |
| `0`       | All checks pass                   | Pipeline continues |
| `1`       | Validation or evaluation failures | Pipeline fails     |

No special configuration is needed. If the command exits with `1`, the pipeline step fails, and downstream steps (like deployment) are skipped.

### Gating in CI

`card evaluate` prints a human-readable report (verdict, violations, warnings, and coverage metrics) and signals the result through its exit code, which is what CI gates on:

```bash theme={null}
mnemom card evaluate card.yaml \
  --tools mcp__browser__navigate,mcp__filesystem__delete \
  --agent my-agent \
  --strict
```

The report lists each violation and warning, then a coverage summary (card actions, mapped, unmapped, and coverage percentage). Without `--strict` only hard policy violations exit `1`; with `--strict` any warning — including an unmapped tool action (sub-100% coverage) — also exits `1`, so the pipeline step fails.

<Note>
  `card evaluate` does not emit machine-readable JSON today. CI pipelines should gate on the exit code (`0` = pass, `1` = fail) rather than parsing stdout.
</Note>

***

## Combining with reputation gates

For comprehensive pre-deploy checks, combine policy gates with reputation gates. Policy gates verify that your governance configuration is correct. Reputation gates verify that your agent's trust score meets your organization's threshold. Together, they ensure both policy correctness and operational trustworthiness before code reaches production.

```yaml theme={null}
# .github/workflows/pre-deploy.yml
name: Pre-Deploy Gates
on:
  push:
    branches: [main]

jobs:
  card-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g @mnemom/mnemom
      - run: mnemom card validate card.yaml
      - run: mnemom card evaluate card.yaml --tools mcp__browser__navigate,mcp__slack__post_message --agent my-agent
        env:
          MNEMOM_API_KEY: ${{ secrets.MNEMOM_API_KEY }}

  reputation-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: mnemom/reputation-check@v1
        with:
          agent-id: mnm-550e8400-e29b-41d4-a716-446655440000
          min-score: 600
          api-key: ${{ secrets.MNEMOM_API_KEY }}
```

Both jobs run in parallel. If either gate fails, the workflow fails and deployment is blocked.

<Note>
  The `reputation-gate` job uses the `mnemom/reputation-check@v1` GitHub Action, which is a standalone action that checks the agent's reputation score against a minimum threshold. See [Embeddable Trust Badges](/guides/reputation-badges#github-action-cicd-reputation-gates) for full configuration options.
</Note>

***

## Setting up the full pipeline

Here is a complete end-to-end workflow that validates on every PR and evaluates on merge to `main`:

<Steps>
  ### Add your API key as a secret

  In GitHub, go to Settings > Secrets and variables > Actions, then add `MNEMOM_API_KEY` with your API key. In GitLab, go to Settings > CI/CD > Variables and add it there with the "Masked" option enabled.

  ### Create the validation workflow

  Add a workflow file that runs static validation on every pull request that modifies card files. This catches schema errors before code review.

  ### Create the evaluation workflow

  Add a second workflow file that runs card evaluation on pushes to `main`. This confirms the card's policy is valid against the agent's tools before deployment proceeds.

  ### Add the reputation gate (optional)

  If your organization enforces minimum trust scores, add the `mnemom/reputation-check` action as a parallel job in your deploy workflow.

  ### Monitor and iterate

  Review pipeline failures in your CI dashboard. Gate downstream steps on the `card evaluate` exit code (`0` = pass, `1` = fail under `--strict`) and route failed jobs to alerting tools like Slack, PagerDuty, or Datadog.
</Steps>

***

## Best practices

* **Run validation on every PR that touches card files.** Static validation is fast and catches the most common mistakes before human review begins.
* **Run evaluation on main branch merges (pre-deploy).** Evaluation confirms the card's policy works against your agent's tools, not just schema correctness.
* **Store card.yaml in version control alongside application code.** This gives you diff visibility, rollback capability, and a clear audit trail for every policy change.
* **Gate on the exit code, not stdout.** `card evaluate` prints a human-readable report and signals pass/fail through its exit code (`0`/`1`); add `--strict` to fail on warnings such as unmapped tool actions. There is no JSON output mode today.
* **Set up notifications for evaluation failures.** Route CI failures to Slack, email, or your incident management tool so the team responds quickly.
* **Keep validation fast by running it first.** Since static validation needs no API call, it should always be the first gate. If it fails, there is no reason to run the slower evaluation step.

***

## See also

* [CLI Reference](/gateway/cli) -- CLI command details for `card validate`, `card evaluate`, and `card publish`
* [Policy Management](/guides/policy-management) -- Full policy workflow from creation to publish
* [Policy DSL Specification](/specifications/policy-dsl) -- Schema reference for policy sections within alignment cards
* [Embeddable Trust Badges](/guides/reputation-badges) -- GitHub Action for reputation gates