microsoft/apm-action

microsoft/apm-action

Description: GitHub Action for Agent Package Manager

Language: TypeScript

License: MIT

Stars: 18

Forks: 4

Open issues: 4

Created: 2026-03-05T20:19:35Z

Pushed: 2026-06-12T05:32:06Z

Default branch: main

Fork: no

Archived: no

README:

APM Action

A GitHub Action that installs APM (Agent Package Manager) and deploys agent primitives (instructions, prompts, skills, agents) into your CI workflows. One line. Zero config.

📖 APM Documentation · Security Model · CI/CD Guide

Usage

- uses: microsoft/apm-action@v1

This installs the APM CLI, reads your apm.yml, and runs apm install.

With options

- uses: microsoft/apm-action@v1
with:
compile: 'true' # generate AGENTS.md after install
apm-version: '0.7.0' # pin a specific APM version
working-directory: './my-project' # custom working directory

Isolated mode (inline dependencies, no apm.yml needed)

- uses: microsoft/apm-action@v1
with:
isolated: 'true'
dependencies: |
- microsoft/apm-sample-package

Setup-only mode (install CLI, then exit)

Just install the APM CLI and put it on PATH, like actions/setup-node. Run any apm command yourself in subsequent steps. No apm.yml required, no install step runs.

- uses: microsoft/apm-action@v1
id: apm
with:
setup-only: 'true'
apm-version: '0.11.0'

- run: apm --version
- run: apm pack -o build --format plugin

setup-only: true is mutually exclusive with pack, bundle, and bundles-file. The action will not read apm.yml, run apm install, or deploy primitives. Sets the apm-version and apm-path outputs so downstream steps can branch on the resolved CLI.

Bundle format (apm vs plugin)

apm pack supports two layouts:

• bundle-format: apm (default) -- produces an APM bundle containing apm.lock.yaml and a .github/ (or .claude/) tree. Restorable by this action via bundle: / bundles-file:. Use this when the consumer is another `microsoft/apm-action` step.
• bundle-format: plugin -- produces a Claude Code plugin bundle with plugin.json at the root and flat primitive directories (agents/, skills/, ...). Use this when publishing to a Claude Code marketplace. Plugin bundles are not restorable by this action; restore them with your plugin tooling.

- uses: microsoft/apm-action@v1
with:
pack: 'true'
bundle-format: 'plugin' # opt-in; default is 'apm'

The bundle-format output reflects the format of the produced or restored bundle.

Pack mode (produce a bundle)

Install dependencies, scan for hidden Unicode threats, and pack into a self-contained .tar.gz archive. Add audit-report to generate a SARIF report alongside the bundle:

- uses: microsoft/apm-action@v1
id: pack
with:
pack: 'true'
target: 'copilot'
audit-report: true

- uses: github/codeql-action/upload-sarif@v3
if: always() && steps.pack.outputs.audit-report-path
with:
sarif_file: ${{ steps.pack.outputs.audit-report-path }}
category: apm-audit

- uses: actions/upload-artifact@v4
with:
name: agent-bundle
path: ${{ steps.pack.outputs.bundle-path }}

This works with all modes — isolated, inline dependencies, or from apm.yml.

Pack with marketplace artifacts (publishing flow)

When apm.yml declares an outputs: map (vendor-format marketplace files), forward the pack-time controls so CI emits exactly the right files for your release:

- uses: microsoft/apm-action@v1
id: pack
with:
pack: 'true'
archive: 'true'
marketplace: 'claude,codex' # which formats to emit (default: all from outputs:)
json-output: 'pack.json' # capture --json report for downstream steps
offline: 'true' # hermetic build using apm.lock.yaml
include-prerelease: 'false' # (default) skip pre-release tags

- name: Stage marketplace artifacts for the release
run: |
cat ${{ steps.pack.outputs.pack-json }}
# bundle-path is empty for marketplace-only projects; use pack-json
# to enumerate bundles + marketplace files + sidecars uniformly.

marketplace-path overrides where each format file is written, useful when you need a vendor-expected filename in the release artifact set:

- uses: microsoft/apm-action@v1
with:
pack: 'true'
marketplace-path: |
claude=marketplace.json
codex=plugins.toml

Vendor-neutral by design. This action does not assume which downstream CLI consumes the marketplace files. It produces the artifacts your apm.yml outputs: map declares; how consumers install them is a separate concern. See the apm marketplace init scaffold for guidance on which formats to declare for which consumer ecosystems.

Release mode (one-step tag publish)

Collapse the canonical release pipeline -- gate, matrix-pack, sha256 sidecars, marketplace.json drift detection, gh release create -- into a single step. Triggered by tag pushes; vendor-neutral underneath (the CLI primitives work identically in GitLab CI, Jenkins, ADO).

on:
push:
tags: ['v*']

jobs:
release:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@v4
- uses: microsoft/apm-action@v1
with:
mode: release
# release-tag defaults to GITHUB_REF_NAME
# release-prerelease: auto (detects -rc/-alpha/-beta/-pre suffix)
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

What it does, in order:

1. apm pack --check-versions --check-clean --json -- fails the job on misaligned per-package versions or uncommitted marketplace.json drift. 2. Detect repo shape (aggregator if plugins//apm.yml files exist, otherwise single-plugin). 3. Matrix-pack every package with apm pack --offline --archive -> tarballs in dist/. 4. Write .sha256 sidecars next to each tarball. 5. Stage marketplace-.json for aggregator shapes. 6. Render a GitHub Step Summary table of the release contents. 7. gh release create (skipped if release-skip-publish: true).

Outputs: packages (JSON), marketplace-drift, release-url, release-tag.

For the non-GitHub-Actions equivalent (the same primitives wrapped in .gitlab-ci.yml, Jenkinsfile, ADO azure-pipelines.yml), see `producer/releasing-from-any-ci.md`.

Restore mode (verified extraction)

Restore primitives from a bundle. The action installs APM (cached across runs) and uses...