CI CD Integration

CI/CD Integration

The same gate that runs in your editor runs in CI, with the same policy and the same verdict. This page shows how to run it in a pipeline, a hardened GitHub Actions example, pre-commit usage, and how to turn on HMAC policy integrity.

Running the gate in CI

The gate has a dedicated CI entry point that needs no install step:

npx -y security-mcp@latest ci:pr-gate

It scopes to the change by default (recent_changes between SECURITY_GATE_BASE_REF and SECURITY_GATE_HEAD_REF), runs the full pipeline, and exits non-zero on a FAIL so the job fails the build.

GitHub Actions example

A least-privilege, SHA-pinned workflow. Pin every action to a commit SHA and check out full history so the diff scope is accurate.

name: security-gate

on:
  pull_request:

permissions:
  contents: read          # least privilege: read-only checkout

jobs:
  security-gate:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout (full history)
        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11  # v4.1.1
        with:
          fetch-depth: 0   # full history so base..head diff is correct

      - name: Setup Node
        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8  # v4.0.2
        with:
          node-version: 20

      - name: Run security gate
        env:
          SECURITY_GATE_BASE_REF: origin/${{ github.base_ref }}
          SECURITY_GATE_HEAD_REF: HEAD
          SECURITY_POLICY_HMAC_KEY: ${{ secrets.SECURITY_POLICY_HMAC_KEY }}
        run: npx -y security-mcp@latest ci:pr-gate

Notes:

• permissions: contents: read keeps the token scoped to what the gate needs. Add only what your own steps require.
• fetch-depth: 0 gives the gate full history so it can compute the base-to-head diff. A shallow clone breaks recent_changes scoping.
• Action SHAs above are illustrative; pin to the SHA of the version you intend to use.

Pre-commit usage

Run the gate locally before code ever leaves the machine. Add a hook that runs the CI gate against staged changes:

# .git/hooks/pre-commit (or via your pre-commit framework)
npx -y security-mcp@latest ci:pr-gate

This catches secrets, vulnerable dependencies, and policy violations at commit time. Pair it with /senior-security-engineer for fix-first remediation before you even reach the hook.

Enabling HMAC policy integrity

To stop a tampered or unsigned policy from weakening your gate in CI:

1. Create a key. Generate a secret of at least 32 bytes and store it as a CI secret named SECURITY_POLICY_HMAC_KEY.

2. Sign locally. With the same key in your environment, run:

   security-mcp sign-policy

3. Commit the sidecar. Commit the generated .hmac file next to your policy (and exceptions) file.

4. Expose the key in CI. Pass the secret into the gate job as shown in the workflow above.

With the key set and the sidecar committed, the gate verifies the policy on every run. If the signature is missing or invalid, the gate applies a HIGH/CRITICAL severity floor rather than trusting the file. Re-sign and re-commit the sidecar whenever you edit the policy. See Configuration and Policy and Security and Hardening.