microsoft/Setup APM

Install agent primitives (skills, instructions, agents) for your CI workflows. One line. Zero config.

View on GitHub

Trust Signals

Scorecard Score: not yet scored
Maintenance Recency: Activelast commit Jun 25, 2026
License: MIT

Pinned Snippet

workflow.ymlSHA-pinned

uses: microsoft/apm-action@d723bb64ed70c135bbaf87d126b721dd2dae0439 # v1.10.0

tags can be moved; commit SHAs can't. why a SHA?

Inputs

name	description	required	default
working-directory	Working directory for execution. In non-isolated mode, this directory must exist and contain your apm.yml. In isolated, pack, or bundle modes the action creates it automatically.	no	.
apm-version	APM CLI version to install (e.g. "0.14.0"). Defaults to a pinned, known-good release. The default is intentionally NOT "latest": pinning the action to a specific APM version prevents downstream workflows from being broken by an unrelated APM release. Pass "latest" explicitly to opt in to floating, or pin to a different tag for reproducibility.	no	0.14.0
script	APM script to run after install (optional — by default only install runs)	no	""
dependencies	YAML array of extra dependencies to install (additive to apm.yml). Supports strings (owner/repo) and objects ({git: url, path: subdir, ref: branch}).	no	""
isolated	Ignore apm.yml and clear pre-existing primitive dirs (instructions/, agents/, skills/, prompts/) under .github/ — install only the inline dependencies	no	false
compile	Run apm compile after install to generate AGENTS.md	no	false
update	Re-resolve dependencies instead of installing from the lockfile. When 'true', the action runs `apm update --yes` in place of `apm install`: it refreshes branch/tag refs to their latest matching commit and rewrites apm.lock.yaml, then proceeds with the normal post-install steps (audit-report, compile, script, pack). Use this in a scheduled or workflow_dispatch job that opens a PR with the updated assets. Requires an apm.yml in the working directory to refresh; the action fails fast if none is present (the dependencies input is an additive inline install, not a manifest refresh). Defaults to 'false' (install pinned versions from the lockfile, the reproducible-by-default behaviour). Mutually exclusive with isolated, setup-only, bundle, bundles-file, and mode.	no	false
pack	Pack a bundle after install. Format is controlled by `bundle-format` (default: apm). Archived output is .zip by default (apm 0.20+); older CLIs emit .tar.gz. Both are accepted on restore.	no	false
bundle-format	Format for `pack: true`. One of: - apm (default) Classic APM bundle: apm.lock.yaml + .github/.claude trees. Round-trips through this action's restore mode. - plugin Claude Code marketplace layout: plugin.json + flat agents/, skills/, commands/, instructions/ dirs. NOTE: plugin-format restore is NOT supported by this action yet -- consume plugin bundles with your plugin tooling, or re-pack with bundle-format: apm.	no	""
bundle	Restore from a bundle (local path or glob pattern). Skips APM installation entirely.	no	""
bundles-file	Path to a UTF-8 text file with one bundle path per line (paths must end in '.zip' or '.tar.gz'). Lines starting with '#' are comments; blank lines are ignored. Glob patterns are NOT expanded -- generate the list yourself with 'find ... \| sort' or equivalent. Bundles are restored in caller-specified order (later bundles win on file collisions; the action emits a warning before the loop runs so the policy is explicit). Mutually exclusive with 'pack' and 'bundle'.	no	""
target	Target harness: copilot, claude, cursor, codex, opencode, gemini, windsurf, agent-skills, or a CSV of any of these. Used with pack: true to set the bundle target, and (isolated: true) to declare the install target in the generated apm.yml. APM v0.12.3+ requires an explicit target signal — set this whenever isolated mode is used outside a checkout that already contains a harness marker.	no	""
archive	Produce a single-file archive instead of a directory (used with pack: true). The archive is .zip by default on apm 0.20+ (.tar.gz on older CLIs); both extensions are recognized.	no	true
marketplace	Forwarded to `apm pack --marketplace=<value>` (used with pack: true). Controls which marketplace formats are emitted alongside the bundle. Accepts a comma-separated list of format names ('claude,codex'), 'all' (every configured format), or 'none' (skip marketplace files). Defaults to whatever is configured in apm.yml's `outputs:` map.	no	""
marketplace-path	Forwarded to `apm pack --marketplace-path FORMAT=PATH` (used with pack: true). Repeatable: one override per line. Each entry must be in `FORMAT=PATH` shape (e.g. `claude=marketplace.json`). Overrides the output path for the named format; useful for placing files at vendor-expected locations within the same release artifact set. Separator is newline only -- `,` is a legal filename character and is not used as a separator.	no	""
json-output	Forwarded to `apm pack --json` (used with pack: true). When set, the action passes --json to the CLI and captures the JSON report to this path (relative to working-directory, or absolute). The JSON report is the source of truth for what was produced -- consume it from downstream steps via the `pack-json` output.	no	""
offline	Forwarded to `apm pack --offline` (used with pack: true). Skips network resolution of marketplace dependency refs. Useful in hermetic CI environments where the resolved versions are already pinned in apm.lock.yaml.	no	false
include-prerelease	Forwarded to `apm pack --include-prerelease` (used with pack: true). Considers pre-release version tags when resolving marketplace dependency refs. Off by default to keep release builds reproducible.	no	false
github-token	GitHub token for API calls (avoids rate limits). Defaults to the automatic GITHUB_TOKEN.	no	${{ github.token }}
audit-report	Generate a SARIF audit report during install/unpack. Set to "true" for default path (apm-audit.sarif), or provide a custom file path.	no	""
setup-only	Install the APM CLI onto PATH and exit. Skips apm install and all project-level operations. Use subsequent steps to run apm commands directly. Mutually exclusive with pack, bundle, bundles-file, isolated, compile, script, dependencies, audit-report, target, bundle-format, marketplace, marketplace-path, json-output, offline, include-prerelease.	no	false
mode	High-level orchestration mode. When set, the action runs a fixed, opinionated pipeline that supersedes the per-flag dispatch (pack/bundle/setup-only/etc.). Supported values: release Validate -> matrix-pack -> sha256 sidecars -> stage marketplace.json -> GH Step Summary -> gh release create. Companion inputs: release-tag, release-name, release-notes, release-draft, release-prerelease, release-skip-publish. Vendor-neutral note: `mode` is a GitHub Actions CONVENIENCE WRAPPER around the apm CLI primitives. The contract lives in the CLI (`apm pack --check-versions --check-clean`, etc.); producers on Jenkins, GitLab, ADO, or local laptops compose the same primitives directly. See docs/producer/releasing-from-any-ci.md. Mutually exclusive with: pack, bundle, bundles-file, setup-only.	no	""
release-tag	Used with mode: release. Tag for the GitHub Release (e.g. v1.2.3). Defaults to GITHUB_REF_NAME when the workflow is triggered on a tag push. Used to derive default release name, default prerelease flag (via the `-` suffix convention), and the marketplace.json filename suffix.	no	""
release-name	Used with mode: release. Display name for the GitHub Release. Defaults to release-tag.	no	""
release-notes	Used with mode: release. Body for the GitHub Release. When empty, the action auto-generates a table of (package, version, bundle, sha256) with a verify hint.	no	""
release-draft	Used with mode: release. Create the GitHub Release as draft. Default: false.	no	false
release-prerelease	Used with mode: release. One of: true, false, auto. `auto` (default) marks the release as a prerelease when the tag contains `-` (semver pre-release suffix, e.g. v1.2.3-rc.1).	no	auto
release-skip-publish	Used with mode: release. Run every step EXCEPT `gh release create`. Useful for dry-runs, local verification, and PR-builds that should validate the pipeline without publishing. Default: false.	no	false

Outputs

name	description
success	Whether the action succeeded (true/false)
primitives-path	Path where agent primitives were deployed (.github)
bundle-path	Path to the packed bundle (only set in pack mode). Empty string when the project produced only marketplace artifacts (no `dependencies:` block in apm.yml) -- consume `pack-json` to discover what was emitted.
bundle-format	Format of the produced or restored bundle: "apm" or "plugin". Set in pack mode and single-bundle restore mode.
pack-json	Path to the captured `apm pack --json` report (set when the `json-output` input was provided). Contains the structured list of every artifact produced by the pack -- bundles, marketplace files, sidecars. Source of truth for downstream steps that need to enumerate outputs without globbing the build/ directory.
audit-report-path	Path to the generated SARIF audit report, if audit-report was enabled
bundles-restored	Number of bundles successfully restored (multi-bundle mode only).
apm-version	Resolved APM CLI version string (e.g. "0.11.0"). Always set.
apm-path	Full path to the apm executable used by the action. Resolved via tool-cache when the action installed APM, or via `which apm` when reusing a pre-existing apm on PATH.
packages	Set by mode: release. JSON array of packaged artifacts produced by the release pipeline. Each element has: {name, version, bundle, sha256, sha256_path} Always emitted as '[]' (empty array) outside mode: release so downstream steps can parse the output unconditionally.
marketplace-drift	Set by mode: release. `true` when `apm pack --check-clean` detected uncommitted changes in the marketplace tree (the action also fails the run in this case); `false` otherwise. Exists for downstream steps that want to branch on drift before the failure surfaces.
release-url	Set by mode: release. URL of the GitHub Release created by this run. Empty when release-skip-publish=true.
release-tag	Set by mode: release. Resolved release tag (input or GITHUB_REF_NAME).