CI Policy Enforcement

Set up automated policy enforcement so every pull request is checked against your organization’s governance rules.

Prerequisites

An organization on GitHub with repositories using APM
apm audit --ci runs 6 baseline consistency checks with no configuration
apm audit --ci --policy org adds 16 policy checks defined in apm-policy.yml

For the full policy schema, see the Policy Reference.

Step 1: Create the org policy

Create apm-policy.yml in your org’s .github repository. APM auto-discovers this file when --policy org is used.

your-org/.github/
└── apm-policy.yml

Start with a minimal policy:

name: "Your Org Policy"
version: "1.0.0"
enforcement: block

dependencies:
  allow:
    - "your-org/**"
  deny:
    - "untrusted-org/**"

mcp:
  self_defined: warn
  transport:
    allow: [stdio, streamable-http]

Commit this to the default branch of your-org/.github.

Step 2: Add baseline CI checks

Add apm audit --ci to your CI pipeline. This runs 6 lockfile consistency checks — no policy file needed:

name: APM Policy Compliance

on:
  pull_request:
    paths:
      - 'apm.yml'
      - 'apm.lock.yaml'
      - '.github/agents/**'
      - '.github/instructions/**'
      - '.github/hooks/**'
      - '.cursor/**'
      - '.claude/**'

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

      - name: Install APM
        run: curl -fsSL https://raw.githubusercontent.com/microsoft/apm/main/install.sh | bash

      - name: Run baseline checks
        run: apm audit --ci

This catches lockfile/manifest drift, missing files, and hidden Unicode — without any policy configuration.

Step 3: Enable policy enforcement

Add --policy org to run the full 16 policy checks on top of baseline:

      - name: Run policy checks
        run: apm audit --ci --policy org --no-cache -f sarif -o policy-report.sarif
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Upload SARIF
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: policy-report.sarif
          category: apm-policy

Key flags:

--policy org — auto-discovers apm-policy.yml from your org’s .github repo
--no-cache — fetches the latest policy (recommended for CI)
-f sarif -o policy-report.sarif — generates SARIF for GitHub Code Scanning

The GITHUB_TOKEN provides read access to the .github repository for policy discovery.

A ready-to-use workflow template is available at templates/policy-ci-workflow.yml in the APM repository.

Step 4: Add repo-level overrides (optional)

Individual repositories can tighten the org policy by adding their own apm-policy.yml with extends: org:

# repo-level apm-policy.yml
name: "Frontend Team Policy"
version: "1.0.0"
extends: org

dependencies:
  deny:
    - "legacy-org/**"  # Additional restriction

unmanaged_files:
  action: deny  # Stricter than org default

Child policies can only tighten constraints — never relax them. See Inheritance for merge rules.

To use a repo-level policy file in CI:

apm audit --ci --policy ./apm-policy.yml

Make it a required check

Configure the workflow as a required status check so PRs cannot merge with policy violations:

Go to repository (or org) Settings → Rules → Rulesets.
Create a ruleset targeting your protected branches.
Add Require status checks to pass.
Select the apm-audit job.

See GitHub Rulesets for org-wide setup.

Alternative policy sources

Local file

apm audit --ci --policy ./policies/apm-policy.yml

URL

apm audit --ci --policy https://example.com/policies/apm-policy.yml

Cross-org

apm audit --ci --policy enterprise-hub/.github

Other CI systems

GitLab CI

apm-policy:
  image: python:3.12-slim
  script:
    - curl -fsSL https://raw.githubusercontent.com/microsoft/apm/main/install.sh | bash
    - apm audit --ci --policy org --no-cache
  rules:
    - changes:
        - apm.yml
        - apm.lock.yaml

Azure Pipelines

- task: Bash@3
  displayName: 'APM Policy Check'
  inputs:
    targetType: inline
    script: |
      curl -fsSL https://raw.githubusercontent.com/microsoft/apm/main/install.sh | bash
      apm audit --ci --policy org --no-cache
  env:
    GITHUB_TOKEN: $(GITHUB_TOKEN)

Exit codes

Code	Meaning
0	All checks passed
1	One or more checks failed

Output formats

Format	Flag	Use case
Text	`-f text` (default)	Human-readable Rich table
JSON	`-f json`	Machine-readable, tooling integration
SARIF	`-f sarif`	GitHub Code Scanning, VS Code

Combine with -o <path> to write to a file.

Governance & Compliance — conceptual overview of APM’s governance model
Policy Reference — full apm-policy.yml schema reference
GitHub Rulesets — enforce policy as a required status check