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 whose instructions require compilation

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 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 GEMINI.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

apm audit --ci catches integration drift by default — no separate git status step required:

      - name: Audit + drift check
        run: apm audit --ci

This single command runs the nine baseline lockfile checks PLUS integration drift detection (default-on) AND replays the install pipeline into a scratch tree to detect missed apm install runs, hand-edited deployed files, and orphaned files. See the Drift Detection guide for details and opt-out (--no-drift).

For repos that commit their deployed files, use the audit-only pattern to catch tampering or stale committed outputs without letting apm install rewrite the checkout first. apm install overwrites managed files before audit runs, which erases any tampered bytes before content-integrity or drift can see them. Pass setup-only: true to the action so it only provides the CLI, then run the full CI gate:

      - uses: microsoft/apm-action@v1
        with:
          setup-only: true
      - name: Audit (audit-only, committed-output gate)
        run: apm audit --ci

In setup-only CI, apm audit --ci now self-hydrates a lock-pinned scratch install when apm_modules/ is absent, so drift and config-consistency still run without mutating the checkout. Repos that gitignore deployed outputs still need those files on disk for deployed-files-present, so keep the full-install pattern for that case. See Audit-only CI pattern for the full recipe and when to use each approach.

We dogfood this

APM’s own repo uses the APM Self-Check job in microsoft/apm’s ci.yml as a reference implementation of the audit-only CI pattern: setup-only: true keeps deployed files untouched, while apm audit --ci self-hydrates its scratch replay from the lockfile so drift and content-integrity can both inspect the checked-out bytes. Use it as a practical example when wiring the audit-only check into your own workflow.

Azure Pipelines

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

ADO with AAD bearer (no PAT)

In orgs that disable PAT creation, use a Workload Identity Federation (WIF) service connection and let APM consume the az session inherited from AzureCLI@2. Do NOT set ADO_APM_PAT — APM falls back to the bearer cleanly only when no PAT env var is present.

steps:
  - task: AzureCLI@2
    displayName: 'APM Install (AAD bearer)'
    inputs:
      azureSubscription: 'my-wif-service-connection'
      scriptType: bash
      scriptLocation: inlineScript
      inlineScript: |
        curl -sSL https://aka.ms/apm-unix | sh
        export PATH="$HOME/.apm/bin:$PATH"
        apm install

For GitHub Actions targeting ADO repos, use azure/login@v2 with OIDC federated credentials so az is signed in before apm install runs:

permissions:
  id-token: write
  contents: read

jobs:
  install:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: azure/login@v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
      - uses: microsoft/apm-action@v1
        # Do not set ADO_APM_PAT -- APM picks up the az session.

See Azure DevOps Services AAD bearer tokens for resolution precedence and verbose output.

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 (the baseline checks plus integration drift detection, no configuration). Add --policy org to enforce organizational rules. For full setup including SARIF integration and GitHub Code Scanning, see the Enforce in CI guide.

For content scanning and hidden Unicode detection, apm install automatically blocks critical findings. Run apm audit for on-demand reporting. See Governance 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)

apm-action@v1 with pack: true emits an APM-format bundle (--format apm --archive) so downstream jobs can restore it via unzip or the action’s restore mode.

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

Pack as standalone plugin

# Export as a Claude Code plugin directory (default format)
- run: apm pack
- uses: actions/upload-artifact@v4
  with:
    name: plugin-bundle
    path: build/

Consume in another job (no APM needed)

The APM bundle layout below assumes the upstream job ran apm-action@v1 with pack: true (or apm pack --format apm --archive). Plugin-format output cannot be restored this way because it does not carry the install-time directory tree.

Migrating from the previous .tar.gz default?

apm pack --archive now writes .zip. If a downstream job still expects build/*.tar.gz, add --archive-format tar.gz to the pack step instead of switching the restore step to unzip.

- uses: actions/download-artifact@v4
  with:
    name: agent-config
- run: unzip -o build/*.zip -d ./

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

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

See the Pack a bundle guide for the full workflow.

Best Practices

• Pin APM version in CI to avoid unexpected changes: pip install apm-cli==0.22.0
• Commit apm.lock.yaml so CI resolves the same dependency versions as local development
• Commit .github/, .claude/, .cursor/, .opencode/, and .gemini/ deployed files so contributors and cloud-based Copilot get agent context without running apm install
• If using apm compile (for Codex, Gemini instructions), 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