Skip to content

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.

ToolRole
APMManages the context your AI agents use — skills, instructions, prompts, agents
gh-awManages the automation that triggers AI agents — event-driven workflows

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

gh-aw natively supports APM through a dependencies: frontmatter field. Declare APM packages directly in your workflow’s frontmatter and gh-aw handles the rest.

Simple array format:

---
on:
pull_request:
types: [opened]
engine: copilot
dependencies:
- microsoft/apm-sample-package
- github/awesome-copilot/skills/review-and-refactor
---
# Code Review
Review the pull request using the installed coding standards and skills.

Object format with options:

---
on:
issues:
types: [opened]
engine: copilot
dependencies:
packages:
- microsoft/apm-sample-package
- your-org/security-compliance
isolated: true
---
# Issue Triage
Analyze the opened issue for security implications.

Each entry is a standard APM package reference — either owner/repo for a full package or owner/repo/path/to/skill for an individual primitive.

How it works:

  1. The gh-aw compiler detects the dependencies: field in your workflow frontmatter.
  2. In the activation job, APM resolves the full dependency tree and packs the result.
  3. In the agent job, the bundle is unpacked into the workspace and the agent discovers the primitives.

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.

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

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

  1. Run apm pack in your CI pipeline to produce a self-contained bundle.
  2. Distribute the bundle as a workflow artifact or commit it to the repository.
  3. Reference the bundled primitives in your workflow.
---
on: pull_request
engine: copilot
imports:
- .github/agents/code-reviewer.md
- .github/agents/security-auditor.md
---
# Code Review
Review the PR using team standards.

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

See the CI/CD Integration guide for details on building and distributing bundles.

APM automatically scans dependencies for hidden Unicode characters during installation. Critical findings block deployment. This applies to both direct apm install and when GitHub Agentic Workflows resolves frontmatter dependencies via apm-action.

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.

When a gh-aw workflow runs in a repository that already has developer-focused instructions (like “use 4-space tabs” or “prefer functional style”), those instructions become noise for an automated agent that should only follow its declared dependencies.

The isolated flag addresses this. When set to true in the object format:

dependencies:
packages:
- your-org/triage-rules
isolated: true

gh-aw clears existing .github/ primitive directories (instructions, skills, agents) before unpacking the APM bundle. The agent sees only the context declared by the workflow, preventing instruction pollution from the host repository.