Add microsoft/apm dependencies support to frontmatter (#19883)

Author: Copilot

.github/aw/actions-lock.json

@@ -169,6 +169,11 @@
       "repo": "super-linter/super-linter",
       "version": "v8.5.0",
       "sha": "61abc07d755095a68f4987d1c2c3d1d64408f1f9"
+    },
+    "microsoft/apm-action@v1": {
+      "repo": "microsoft/apm-action",
+      "version": "v1",
+      "sha": "92d6dc8046ad61b340662adefd2f997bf93d2987"
     }
   }
 }

docs/src/content/docs/reference/frontmatter.md

@@ -132,6 +132,26 @@ plugins:
 
 Each plugin repository must be specified in `org/repo` format. The compiler generates installation steps that run after the engine CLI is installed but before workflow execution begins.
 
+### APM Dependencies (`dependencies:`)
+
+Specifies [microsoft/apm](https://github.com/microsoft/apm) packages to install before workflow execution. When present, the compiler emits a step using the `microsoft/apm-action` action to install the listed packages.
+
+APM (Agent Package Manager) manages AI agent primitives such as skills, prompts, instructions, agents, and hooks. Packages can depend on other packages and APM resolves the full dependency tree.
+
+```yaml wrap
+dependencies:
+  - microsoft/apm-sample-package
+  - github/awesome-copilot/skills/review-and-refactor
+  - anthropics/skills/skills/frontend-design
+```
+
+Each entry is an APM package reference. Supported formats:
+
+- `owner/repo` — full APM package
+- `owner/repo/path/to/skill` — individual skill or primitive from a repository
+
+The compiler generates an `Install APM dependencies` step that runs after the engine CLI installation steps.
+
 ### Runtimes (`runtimes:`)
 
 Override default runtime versions for languages and tools used in workflows. The compiler automatically detects runtime requirements from tool configurations and workflow steps, then installs the specified versions.

pkg/parser/schemas/main_workflow_schema.json

@@ -7516,6 +7516,16 @@
           }
         }
       ]
+    },
+    "dependencies": {
+      "description": "List of APM package references to install (e.g., 'org/repo' or 'org/repo/path/to/skill').",
+      "examples": [["microsoft/apm-sample-package", "acme/custom-tools"]],
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-zA-Z0-9_-]+/[a-zA-Z0-9_./-]+$",
+        "description": "APM package reference in the format 'org/repo' or 'org/repo/path/to/skill'"
+      }
     }
   },
   "additionalProperties": false,
@@ -8147,7 +8157,9 @@
             "repositories": {
               "type": "array",
               "description": "Repositories to grant the token access to. Defaults to the current repository. Use [\"*\"] for org-wide access.",
-              "items": { "type": "string" },
+              "items": {
+                "type": "string"
+              },
               "examples": [["repo-a", "repo-b"], ["*"]]
             }
           },

pkg/workflow/action_pins_test.go

@@ -297,9 +297,9 @@ func TestApplyActionPinToStep(t *testing.T) {
 func TestGetActionPinsSorting(t *testing.T) {
 	pins := getActionPins()
 
-	// Verify we got all the pins (34 as of March 2026)
-	if len(pins) != 34 {
-		t.Errorf("getActionPins() returned %d pins, expected 34", len(pins))
+	// Verify we got all the pins (35 as of March 2026)
+	if len(pins) != 35 {
+		t.Errorf("getActionPins() returned %d pins, expected 35", len(pins))
 	}
 
 	// Verify they are sorted by version (descending) then by repository name (ascending)

pkg/workflow/apm_dependencies.go

@@ -0,0 +1,43 @@
+package workflow
+
+import (
+	"github.com/github/gh-aw/pkg/logger"
+)
+
+var apmDepsLog = logger.New("workflow:apm_dependencies")
+
+// GenerateAPMDependenciesStep generates a GitHub Actions step that installs APM packages
+// using the microsoft/apm-action action. The step is emitted when the workflow frontmatter
+// contains a non-empty `dependencies` list in microsoft/apm format.
+//
+// Parameters:
+//   - apmDeps: APM dependency configuration extracted from frontmatter
+//   - data: WorkflowData used for action pin resolution
+//
+// Returns a GitHubActionStep, or an empty step if apmDeps is nil or has no packages.
+func GenerateAPMDependenciesStep(apmDeps *APMDependenciesInfo, data *WorkflowData) GitHubActionStep {
+	if apmDeps == nil || len(apmDeps.Packages) == 0 {
+		apmDepsLog.Print("No APM dependencies to install")
+		return GitHubActionStep{}
+	}
+
+	apmDepsLog.Printf("Generating APM dependencies step: %d packages", len(apmDeps.Packages))
+
+	// Resolve the pinned action reference for microsoft/apm-action.
+	actionRef := GetActionPin("microsoft/apm-action")
+
+	// Build step lines. The `dependencies` input uses a YAML block scalar (`|`)
+	// so each package is written as an indented list item on its own line.
+	lines := []string{
+		"      - name: Install APM dependencies",
+		"        uses: " + actionRef,
+		"        with:",
+		"          dependencies: |",
+	}
+
+	for _, dep := range apmDeps.Packages {
+		lines = append(lines, "            - "+dep)
+	}
+
+	return GitHubActionStep(lines)
+}

pkg/workflow/apm_dependencies_compilation_test.go

@@ -0,0 +1,132 @@
+//go:build integration
+
+package workflow
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/github/gh-aw/pkg/testutil"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestAPMDependenciesCompilationSinglePackage(t *testing.T) {
+	tmpDir := testutil.TempDir(t, "apm-deps-single-test")
+
+	workflow := `---
+engine: copilot
+on: workflow_dispatch
+permissions:
+  issues: read
+  pull-requests: read
+dependencies:
+  - microsoft/apm-sample-package
+---
+
+Test with a single APM dependency
+`
+
+	testFile := filepath.Join(tmpDir, "test-apm-single.md")
+	err := os.WriteFile(testFile, []byte(workflow), 0644)
+	require.NoError(t, err, "Failed to write test file")
+
+	compiler := NewCompiler()
+	err = compiler.CompileWorkflow(testFile)
+	require.NoError(t, err, "Compilation should succeed")
+
+	lockFile := strings.Replace(testFile, ".md", ".lock.yml", 1)
+	content, err := os.ReadFile(lockFile)
+	require.NoError(t, err, "Failed to read lock file")
+
+	lockContent := string(content)
+
+	assert.Contains(t, lockContent, "Install APM dependencies",
+		"Lock file should contain APM dependencies step name")
+	assert.Contains(t, lockContent, "microsoft/apm-action",
+		"Lock file should reference the microsoft/apm-action action")
+	assert.Contains(t, lockContent, "dependencies: |",
+		"Lock file should use block scalar for dependencies input")
+	assert.Contains(t, lockContent, "- microsoft/apm-sample-package",
+		"Lock file should list the dependency package")
+}
+
+func TestAPMDependenciesCompilationMultiplePackages(t *testing.T) {
+	tmpDir := testutil.TempDir(t, "apm-deps-multi-test")
+
+	workflow := `---
+engine: copilot
+on: workflow_dispatch
+permissions:
+  issues: read
+  pull-requests: read
+dependencies:
+  - microsoft/apm-sample-package
+  - github/awesome-copilot/skills/review-and-refactor
+  - anthropics/skills/skills/frontend-design
+---
+
+Test with multiple APM dependencies
+`
+
+	testFile := filepath.Join(tmpDir, "test-apm-multi.md")
+	err := os.WriteFile(testFile, []byte(workflow), 0644)
+	require.NoError(t, err, "Failed to write test file")
+
+	compiler := NewCompiler()
+	err = compiler.CompileWorkflow(testFile)
+	require.NoError(t, err, "Compilation should succeed")
+
+	lockFile := strings.Replace(testFile, ".md", ".lock.yml", 1)
+	content, err := os.ReadFile(lockFile)
+	require.NoError(t, err, "Failed to read lock file")
+
+	lockContent := string(content)
+
+	assert.Contains(t, lockContent, "Install APM dependencies",
+		"Lock file should contain APM dependencies step name")
+	assert.Contains(t, lockContent, "microsoft/apm-action",
+		"Lock file should reference the microsoft/apm-action action")
+	assert.Contains(t, lockContent, "- microsoft/apm-sample-package",
+		"Lock file should include first dependency")
+	assert.Contains(t, lockContent, "- github/awesome-copilot/skills/review-and-refactor",
+		"Lock file should include second dependency")
+	assert.Contains(t, lockContent, "- anthropics/skills/skills/frontend-design",
+		"Lock file should include third dependency")
+}
+
+func TestAPMDependenciesCompilationNoDependencies(t *testing.T) {
+	tmpDir := testutil.TempDir(t, "apm-deps-none-test")
+
+	workflow := `---
+engine: copilot
+on: workflow_dispatch
+permissions:
+  issues: read
+  pull-requests: read
+---
+
+Test without APM dependencies
+`
+
+	testFile := filepath.Join(tmpDir, "test-apm-none.md")
+	err := os.WriteFile(testFile, []byte(workflow), 0644)
+	require.NoError(t, err, "Failed to write test file")
+
+	compiler := NewCompiler()
+	err = compiler.CompileWorkflow(testFile)
+	require.NoError(t, err, "Compilation should succeed")
+
+	lockFile := strings.Replace(testFile, ".md", ".lock.yml", 1)
+	content, err := os.ReadFile(lockFile)
+	require.NoError(t, err, "Failed to read lock file")
+
+	lockContent := string(content)
+
+	assert.NotContains(t, lockContent, "Install APM dependencies",
+		"Lock file should not contain APM dependencies step when no dependencies specified")
+	assert.NotContains(t, lockContent, "microsoft/apm-action",
+		"Lock file should not reference microsoft/apm-action when no dependencies specified")
+}