feat: GitHub Agentic Workflows integration — agent primitive packaging for CI

[danielmeppiel]

Context

GitHub Agentic Workflows (GH AW) run coding agents (Copilot CLI, Claude Code, Codex) on GitHub Actions runners. These workflows need agent primitives (skills, instructions, custom agents) but lack dependency management — authors resort to git clone + cat SKILL.md in bash steps, with no versioning and no reproducibility.

APM already solves this for local development. A GitHub Actions runner is just another environment.

Capability	GH AW imports:	Raw steps:	APM
Transitive dependencies	No	Manual	Yes
Lockfile (exact SHA)	Commit-based cache	No	Yes
Skill directories	Single files only	Manual	Yes
Instruction scoping (applyTo:)	No	No	Yes
Version pinning (semver/tags)	@ref only	Manual	Yes
Cross-engine (Copilot/Claude/Codex)	Copilot only	Manual	Yes

The Design: Two Tiers

Tier 1: One-Line Pre-Step (Works Today)

Zero changes to GH AW. Uses the existing steps: frontmatter:

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

steps:
  - uses: microsoft/apm-action@v1
---

# Issue Triage

Triage this issue using the installed compliance rules and security skills.

The repo has apm.yml + apm.lock. The action runs apm install, primitives deploy to .github/ on the runner, the coding agent discovers them naturally.

Tier 2: Inline Dependencies (APM Enhancement)

Declare extra agent dependencies directly in the workflow. The dependencies input uses the same YAML array syntax as dependencies.apm in apm.yml — strings and objects both work natively:

---
on:
  issues:
    types: [opened]
engine:
  id: copilot
  agent: security-auditor

steps:
  - uses: microsoft/apm-action@v1
    with:
      dependencies: |
        - microsoft/compliance-rules#v2.1.0
        - myorg/security-scanning-skill
        - git: https://gitlab.com/acme/standards.git
          path: instructions/security
          ref: v2.0
---

# Issue Triage

Analyze the opened issue for security implications using the compliance
rules and security scanning skill.

How it works:

1. apm install — installs from apm.yml (if it exists)
2. YAML-parse the dependencies input, then apm install <each> on top
3. If compile: true, generate AGENTS.md

Always additive — like npm install <pkg> is additive to package.json. For the rare case where CI should ignore the project manifest, set skip-manifest: true.

Future: Native GH AW Frontmatter (Collaborative)

Long-term, GH AW could recognize APM natively — no steps: boilerplate:

---
on: issues
engine: copilot

dependencies:
  apm:
    - microsoft/compliance-rules#v2.1.0
    - myorg/security-scanning-skill
---

This requires collaboration with the GH AW team and is out of scope for now.

UX: Before and After

Before (Today)

steps:
  - name: Download compliance rules
    run: |
      mkdir -p /tmp/skills
      git clone https://github.com/microsoft/compliance-rules /tmp/skills/compliance
      git clone https://github.com/myorg/security-skill /tmp/skills/security
      cat /tmp/skills/compliance/SKILL.md
      cat /tmp/skills/security/SKILL.md

After (With APM)

steps:
  - uses: microsoft/apm-action@v1
    with:
      dependencies: |
        - microsoft/compliance-rules#v2.1.0
        - myorg/security-skill#v1.0.0

Versioned. Locked. Reproducible. One step.

Action Inputs

Input	Default	Description
dependencies	''	YAML list of extra packages (same format as apm.yml)
compile	false	Generate AGENTS.md after install
skip-manifest	false	Ignore the repo's apm.yml
working-directory	.	Where to run
apm-version	latest	APM version to install
script	''	Post-install script to run

Key Design Decisions

• No isolation mode. Copilot CLI discovers primitives from .github/ in the workspace root. Skills, hooks, and agents have no env var override for alternative paths. CI runners are ephemeral — instruction "pollution" is a non-issue on a disposable runner. For rare cases where this is needed, use skip-manifest: true.
• Compile is opt-in. Most workflows just need apm install to deploy primitives to .github/.
• YAML format only. The dependencies input is YAML-parsed — same format as apm.yml. Supports both string deps (owner/repo#ref) and object deps ({git: URL, path: X, ref: Y} from feat: Generic git URL support (GitLab, Bitbucket, any host) #150). No dual-format detection.
• Additive by default. CI agents need the project's own primitives plus potentially more. skip-manifest exists for the edge case.

Status

• apm-action defaults to install-only (no compile unless requested)
• Validated apm-action works as a GH AW steps: pre-step
• feat: Generic git URL support (GitLab, Bitbucket, any host) #150 merged — generic git URL + object-form deps
• Implement YAML-parsed dependencies input (replaces current newline format)
• Add skip-manifest input
• Update test workflow with string + object dep scenarios
• Release apm-action@v1
• Document GH AW integration in docs/
• Create example GH AW workflow

References

• GitHub Agentic Workflows
• GH AW steps: frontmatter
• apm-action repo
• feat: Generic git URL support (GitLab, Bitbucket, any host) #150 — Generic git URL + object-form dependency support (merged)

[danielmeppiel]

✅ All deliverables completed — closing this issue

The microsoft/apm-action GitHub Action has been built, validated end-to-end, and released to the GitHub Marketplace.

Deliverables

Item	Status	Reference
apm-action defaults to install-only	✅	Default behavior — no script needed
Validated as GH AW steps: pre-step	✅	Run 22749832020
YAML-parsed dependencies input	✅	Uses js-yaml, same syntax as apm.yml
isolated mode (was skip-manifest)	✅	Skips apm.yml, uses only dependencies input
Release apm-action@v1	✅	v1.0.0 + floating v1 tag
GitHub Marketplace listing	✅	Setup APM
Example GH AW workflow	✅	apm-demo.md in repo
Compact summary output	✅	PR #4 — survives GH AW 500-char truncation

End-to-end proof (Run 22749832020)

The GH AW demo workflow successfully:

1. Installed APM v0.7.4 via the install script
2. Resolved and installed microsoft/apm-sample-package (2 prompts, 1 agent, 2 skills)
3. Copilot CLI discovered and used all APM-deployed primitives inside the agent sandbox

Key log output from the agent job:

✅ APM + GitHub Agentic Workflows Integration: **CONFIRMED**
All APM-deployed primitives are present and readable.

Upstream issue filed

GH AW step summary truncation (500-char limit, false ✓ on failed bash, dangling $GITHUB_STEP_SUMMARY) tracked in github/gh-aw#19810.

Documentation

GH AW integration docs will be added as a follow-up (separate issue/PR) to keep this scope clean.