GitHub Agentic Workflows

GitHub Agentic Workflows (gh-aw) lets you write repository automation in markdown and run it as GitHub Actions using AI agents. APM and gh-aw have a native integration: gh-aw recognizes APM packages as first-class dependencies.

How They Work Together

Tool	Role
APM	Manages the context your AI agents use — skills, instructions, prompts, agents
gh-aw	Manages the automation that triggers AI agents — event-driven workflows

APM defines what agents know. gh-aw defines when and how they act.

Integration Approaches

Shared apm.md Import (Recommended)

gh-aw ships a shared apm.md workflow component that turns APM packages into gh-aw dependencies. Import it in your workflow’s frontmatter and pass the packages you want.

---
on:
  pull_request:
    types: [opened]
engine: copilot

imports:
  - uses: shared/apm.md
    with:
      packages:
        - microsoft/apm-sample-package
        - github/awesome-copilot/skills/review-and-refactor
        - your-org/security-compliance#v1.4.0
---

# Code Review

Review the pull request using the installed coding standards and skills.

Package reference formats:

Format	Description
`owner/repo`	Full APM package (skills/agents/instructions under `.apm/`)
`owner/repo/path/to/primitive`	Individual primitive (skill, instruction, plugin, etc.) from any repository, regardless of layout
`owner/repo#ref` or `owner/repo/path/to/primitive#ref`	Pinned to a tag, branch, or commit SHA, for either a full package or a specific primitive

The per-primitive path form is what makes github/awesome-copilot/skills/review-and-refactor work — the awesome-copilot repo lays skills out at /skills/<name>/, not under .apm/. Use this form to consume skills from existing repositories without restructuring them. See Anatomy of an APM Package for the full source-vs-output model.

How it works:

The gh-aw compiler detects the shared/apm.md import and adds a dedicated apm job to the compiled workflow.
The apm job runs microsoft/apm-action to install packages and uploads a bundle archive as a GitHub Actions artifact.
The agent job downloads and unpacks the bundle as pre-steps, making all primitives available at runtime.

The APM compilation target is automatically inferred from the configured engine: field (copilot, claude, or all for other engines). No manual target configuration is needed.

Packages are fetched using gh-aw’s cascading token fallback: GH_AW_PLUGINS_TOKEN -> GH_AW_GITHUB_TOKEN -> GITHUB_TOKEN.

Vendor the canonical shared/apm.md

shared/apm.md is a local file that gh-aw resolves at .github/workflows/shared/apm.md in your repository — not a remote import. Two copies exist in the wild: one in microsoft/apm (canonical, current) and one in github/gh-aw (vendored, may lag).

To get the canonical version with multi-org GitHub App auth (apps:) and multi-bundle restore:

mkdir -p .github/workflows/shared
curl -sSL https://raw.githubusercontent.com/microsoft/apm/main/.github/workflows/shared/apm.md \
  > .github/workflows/shared/apm.md

Check whether your vendored copy is current by comparing the Source of truth: and apm-action pin: lines near the top of the file with the canonical copy linked above.

apm-action Pre-Step

For more control over the installation process, use microsoft/apm-action@v1 as an explicit workflow step. This approach runs apm install directly, giving you access to the full APM CLI. To also compile, add compile: true to the action configuration.

---
on:
  pull_request:
    types: [opened]
engine: copilot

steps:
  - name: Install agent primitives
    uses: microsoft/apm-action@v1
    with:
      script: install
    env:
      GITHUB_TOKEN: ${{ github.token }}
---

# Code Review

Review the PR using the installed coding standards.

The repo needs an apm.yml with dependencies and apm.lock.yaml for reproducibility. The action runs as a pre-agent step, deploying primitives to .github/ where the agent discovers them.

When to use this over frontmatter dependencies:

Custom compilation options (specific targets, flags)
Running additional APM commands (audit, preview)
Workflows that need apm.yml-based configuration
Debugging dependency resolution

Using APM Bundles

For sandboxed environments where network access is restricted during workflow execution, use pre-built APM bundles:

Run apm pack --format apm --archive in your CI pipeline to produce a self-contained APM bundle (the format restorable via tar xzf or apm-action restore mode).
Distribute the bundle as a workflow artifact or commit it to the repository.
Reference the bundled primitives directly from .github/agents/ in your workflow.

Bundles resolve full dependency trees ahead of time, so workflows need zero network access at runtime.

See the CI/CD Integration guide and Pack & Distribute for details on building and distributing bundles. For routing live install traffic through an enterprise proxy instead, see Registry Proxy & Air-gapped.

Content Scanning

APM automatically scans dependencies for hidden Unicode characters during installation. Critical findings block deployment. This applies to both direct apm install and when gh-aw resolves packages via shared/apm.md.

For CI visibility into scan results (SARIF reports, step summaries), see the CI/CD Integration guide.

For details on what APM detects, see Content scanning.