APM in CI/CD

APM integrates into your CI/CD pipeline to ensure agent context is always up to date.

GitHub Actions

Use the official apm-action to install APM and run commands in your workflows:

.github/workflows/apm.yml

name: APM
on:
  push:
    branches: [main]
  pull_request:

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

      - name: Install APM packages
        uses: microsoft/apm-action@v1
        # Optional: add compile: true if targeting Codex, Gemini,
        # or other tools without native APM integration

Private Dependencies

For private repositories, pass a token via the workflow env: block. See the Authentication guide for all supported tokens and priority rules.

      - name: Install APM packages
        uses: microsoft/apm-action@v1
        env:
          GITHUB_APM_PAT: ${{ secrets.APM_PAT }}

Verify Compiled Output (Optional)

If your project uses apm compile to target tools like Cursor, Codex, or Gemini, add a check to ensure compiled output stays in sync:

      - name: Check for drift
        run: |
          apm compile
          if [ -n "$(git status --porcelain -- AGENTS.md CLAUDE.md)" ]; then
            echo "Compiled output is out of date. Run 'apm compile' locally and commit."
            exit 1
          fi

This step is not needed if your team only uses GitHub Copilot and Claude, which read deployed primitives natively.

Verify Deployed Primitives

To ensure .github/, .claude/, .cursor/, and .opencode/ integration files stay in sync with apm.yml, add a drift check:

      - name: Check APM integration drift
        run: |
          apm install
          if [ -n "$(git status --porcelain -- .github/ .claude/ .cursor/ .opencode/)" ]; then
            echo "APM integration files are out of date. Run 'apm install' and commit."
            exit 1
          fi

This catches cases where a developer updates apm.yml but forgets to re-run apm install.

Azure Pipelines

steps:
  - script: |
      curl -sSL https://aka.ms/apm-unix | sh
      apm install
      # Optional: only if targeting Codex, Gemini, or similar tools
      # apm compile
    displayName: 'APM Install'
    env:
      ADO_APM_PAT: $(ADO_PAT)

General CI

For any CI system with Python available:

pip install apm-cli
apm install
# Optional: only if targeting Codex, Gemini, or similar tools
# apm compile --verbose

Governance with apm audit

apm audit --ci verifies lockfile consistency in CI (6 baseline checks, no configuration). Add --policy org to enforce organizational rules (16 additional checks). For full setup including SARIF integration and GitHub Code Scanning, see the CI Policy Enforcement guide.

For content scanning and hidden Unicode detection, apm install automatically blocks critical findings. Run apm audit for on-demand reporting. See Governance & Compliance for the full governance model.

Pack & Distribute

Use apm pack in CI to build a distributable bundle once, then consume it in downstream jobs without needing APM installed.

Pack in CI (build once)

- uses: microsoft/apm-action@v1
  with:
    pack: true
- uses: actions/upload-artifact@v4
  with:
    name: agent-config
    path: build/*.tar.gz

Pack as standalone plugin

# Export as standalone plugin
- run: apm pack --format plugin
- uses: actions/upload-artifact@v4
  with:
    name: plugin-bundle
    path: build/*.tar.gz

Consume in another job (no APM needed)

- uses: actions/download-artifact@v4
  with:
    name: agent-config
- run: tar xzf build/*.tar.gz -C ./

Or use the apm-action restore mode to unpack a bundle directly:

- uses: microsoft/apm-action@v1
  with:
    bundle: ./agent-config.tar.gz

See the Pack & Distribute guide for the full workflow.

Best Practices

• Pin APM version in CI to avoid unexpected changes: pip install apm-cli==0.7.7
• Commit apm.lock.yaml so CI resolves the same dependency versions as local development
• Commit .github/, .claude/, .cursor/, and .opencode/ deployed files so contributors and cloud-based Copilot get agent context without running apm install
• If using apm compile (for Codex, Gemini), run it in CI and fail the build if the output differs from what’s committed
• Use GITHUB_APM_PAT for private dependencies; never use the default GITHUB_TOKEN for cross-repo access