shared/apm.md: align docs with canonical microsoft/apm source; deprecate vendored copy

[danielmeppiel]

Summary

shared/apm.md is the workflow component that lets gh-aw users install APM packages as agent dependencies. Two copies exist in the wild and they have diverged enough that vendoring one over the other materially changes which features users get:

Copy	Path	apm-action pin	App auth	apps:[] multi-org	bundles-file: multi-bundle restore	Input shape
canonical	microsoft/apm/.github/workflows/shared/apm.md	v1.5.0	yes	yes	yes	modern (packages: + optional apps:)
vendored here	github/gh-aw/.github/workflows/shared/apm.md	v1.4.2	no	no	no	uses deprecated dependencies: input on apm-action

The two relevant lines in this repo today:

• .github/workflows/shared/apm.md line 66: uses: microsoft/apm-action@v1.4.2
• .github/workflows/shared/apm.md line 70: dependencies: ${{ steps.apm_prep.outputs.deps }}

apm-action v1.5.0 (release) shipped:

1. Multi-org GitHub App auth via an apps:[] input — one App credential group per matrix replica, each minting its own installation token. Closes the cross-org private-package gap that App auth alone could not solve.
2. bundles-file: input that restores N apm bundles in a single action call (replaces the single bundle: input).
3. Deprecation of the dependencies: input (microsoft/apm CHANGELOG #864) — still works in v1.x, scheduled for removal in v2.

The reference page at https://github.github.com/gh-aw/reference/dependencies/ tells users imports: - uses: shared/apm.md without saying it is a local file or which copy to source from. Users hit Stack Overflow / Google → vendor this repo's older copy → silently miss multi-org auth and the modern restore path. There is no error path that surfaces the version drift.

Proposal (decoupled tiers — review separately if useful)

Tier 1 — Documentation fix (low effort, high impact, no runtime change)

File: docs/src/content/docs/reference/dependencies.md (renders at https://github.github.com/gh-aw/reference/dependencies/)

Concrete edits:

1. After the existing "import the shared/apm.md workflow" paragraph (around line 10), add a new section explaining the local-file model. Suggested copy:

   ## Where `shared/apm.md` comes from
   
   `shared/apm.md` is a **local workflow file** that gh-aw resolves at
   `.github/workflows/shared/apm.md` in your repository — it is not a remote
   import (the `uses:` syntax inside `imports:` is gh-aw's local-import shape,
   not GitHub Actions' `uses: owner/repo@ref`).
   
   You must vendor the file into your own repo. The canonical, current source
   is maintained by [microsoft/apm](https://github.com/microsoft/apm/blob/main/.github/workflows/shared/apm.md):
   
   ```bash
   mkdir -p .github/workflows/shared
   curl -sSL https://raw.githubusercontent.com/microsoft/apm/main/.github/workflows/shared/apm.md \
     > .github/workflows/shared/apm.md

   The canonical version pins microsoft/apm-action@v1.5.0 and supports
   multi-org GitHub App authentication (apps:[]) and multi-bundle restore.
   To check whether your vendored copy is current, compare the Source of truth: and apm-action pin: lines near the top of the file with the
   canonical copy linked above.

2. In the existing Reference table at the bottom of the page, add one row:

   | shared/apm.md (canonical) | https://github.com/microsoft/apm/blob/main/.github/workflows/shared/apm.md |

3. Optionally extend the existing dependencies:-deprecation note (line 12) to mention that the apm-action's own dependencies: input on the action call inside shared/apm.md is also deprecated in favour of packages:/apps: — so anyone who hand-edits the vendored file should not reach for dependencies:.

Tier 2 — Deprecate this repo's vendored copy in place

File: .github/workflows/shared/apm.md

Two non-mutually-exclusive options. I have a slight preference for Option A because it removes the version drift entirely, but Option B is the lower-risk path if you want to keep gh-aw self-contained.

Option A — Bring the vendored copy up to v1.5.0 (parity with canonical)

Wholesale-replace the file body with the current canonical content at https://github.com/microsoft/apm/blob/main/.github/workflows/shared/apm.md. The file size grows from ~163 lines to ~330 because of the matrix fan-out + apm-prep job, but the public interface (imports: - uses: shared/apm.md\nwith:\n packages:) is fully backward-compatible with the existing call shape: the new apps:, app-id:, private-key:, owner: inputs are all optional. Existing gh-aw consumers who only set packages: see no behavioural change.

To make this auditable, the canonical microsoft/apm copy now includes a 2-line version header at the top:

# Source of truth: https://github.com/microsoft/apm/blob/main/.github/workflows/shared/apm.md
# apm-action pin:  microsoft/apm-action@v1.5.0

Option B — Add a deprecation header pointing at microsoft/apm, keep the body as-is

Prepend the existing file with:

# DEPRECATED: This vendored copy is pinned to apm-action@v1.4.2 and uses the
# deprecated `dependencies:` input. The canonical, current source lives at:
#   https://github.com/microsoft/apm/blob/main/.github/workflows/shared/apm.md
#
# To upgrade your repo:
#   curl -sSL https://raw.githubusercontent.com/microsoft/apm/main/.github/workflows/shared/apm.md \
#     > .github/workflows/shared/apm.md
#
# Tracking issue: <link to this issue>

This signals deprecation without forcing a behavioural change on anyone reading it from this repo's git history.

Out of scope (deliberately)

• Deletion of this repo's .github/workflows/shared/apm.md — anyone who already vendored it is fine; their local file is frozen by design. We are not asking for deletion; both Options A and B above leave the file in place.
• Remote-import support (e.g. uses: microsoft/apm/.github/workflows/shared/apm.md@v0.11.0) — would eliminate copy-and-vendor entirely. Worth a separate gh-aw feature request when bandwidth allows; not blocking on it here.
• Changes to shared/apm.md's public input surface — nothing in this issue asks gh-aw to break or rename anything users put in their workflow frontmatter.

Implementation guide for an agent picking this up

If you take this issue:

1. Read the canonical copy at https://raw.githubusercontent.com/microsoft/apm/main/.github/workflows/shared/apm.md and compare against .github/workflows/shared/apm.md in this repo. Note the three call shapes documented in the canonical's docstring (public packages only / single-app / multi-app via apps:[]).
2. Tier 1 — docs PR: edit docs/src/content/docs/reference/dependencies.md per the diff sketches above. Run the gh-aw docs build (whatever the repo uses — see docs/ README) to confirm the page renders.
3. Tier 2 — workflow PR (separate PR recommended):
   • Option A path: replace .github/workflows/shared/apm.md body with canonical content. Then run gh aw compile from the repo root to regenerate any consumers. Verify that any internal gh-aw .lock.yml files that import shared/apm.md recompile cleanly with microsoft/apm-action@v1.5.0 SHA-pinned. Any test workflows that import shared/apm.md and do not pass apps: should keep working unchanged.
   • Option B path: prepend the deprecation header. No recompile needed since the runtime body is unchanged.
4. Validation:
   • For Option A: pick one workflow in the repo that imports shared/apm.md (search .github/workflows/*.md for uses: shared/apm.md) and confirm its .lock.yml regenerates with the new SHA + bundles-file: restore step.
   • The apps:[] path itself cannot be CI-validated without real cross-org GitHub App credentials; that path is exercised by microsoft/apm-action's own test suite and by microsoft/apm's PR review panel runs.
5. Backlinks: in the PR description, link this issue, microsoft/apm-action v1.5.0 release, and microsoft/apm PR #982 (the canonical-side change that this is paired with).

Happy to send the PRs from microsoft/apm side if you prefer — just say the word and I'll open one against this repo with whichever option you pick.

References

• microsoft/apm-action v1.5.0 release notes
• microsoft/apm-action#30 — bundles-file: input + multi-bundle restore
• microsoft/apm#982 — apps[] + matrix fan-out in canonical shared/apm.md
• microsoft/apm#1026 — STATUS-banner cleanup + lock files at v1.5.0 + version header convention
• microsoft/apm gh-aw integration docs
• microsoft/apm CHANGELOG — dependencies: deprecation