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
Section titled “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
Section titled “Integration Approaches”Frontmatter Dependencies (Recommended)
Section titled “Frontmatter Dependencies (Recommended)”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:
- The gh-aw compiler detects the
dependencies:field in your workflow frontmatter. - In the activation job, APM resolves the full dependency tree and packs the result.
- 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.
apm-action Pre-Step
Section titled “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
Section titled “Using APM Bundles”For sandboxed environments where network access is restricted during workflow execution, use pre-built APM bundles:
- Run
apm packin your CI pipeline to produce a self-contained bundle. - Distribute the bundle as a workflow artifact or commit it to the repository.
- Reference the bundled primitives in your workflow.
---on: pull_requestengine: copilotimports: - .github/agents/code-reviewer.md - .github/agents/security-auditor.md---
# Code ReviewReview 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.
Content Scanning
Section titled “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 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.
Isolated Mode
Section titled “Isolated Mode”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: truegh-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.