Expose `apm-version` as an import input on `shared/apm.md`

[anthonymastreanvae]

Summary

Consumers vendor shared/apm.md (via gh aw add microsoft/apm/.github/workflows/shared/apm.md) and import it from their agentic workflows. The shared workflow pins the apm CLI version only through microsoft/apm-action's built-in default — it does not expose apm-version as an import input. To run a newer apm CLI than the action's default, a consumer must hand-edit the vendored shared/apm.md (the apm-version on both the Pack and Restore apm-action steps). That edit is fragile: gh aw update re-merges from upstream and --no-merge reverts it outright.

Please add apm-version to the import schema and thread it into both apm-action invocations, so consumers can set it from their own workflow's with: block.

Why this matters

The apm CLI version is not cosmetic — it changes what apm install/apm pack deliver. For example, older apm packs primitives only, while newer apm also carries package documentation/knowledge-base files that agents reference at runtime. Behavior fixes ship in the CLI too — e.g. skill-bundle relative-link rewriting (#1625, PR #1657) was broken for skills and fixed in a later release. Consumers who need any of this currently have no first-class way to opt into a newer CLI; they must patch a vendored file and re-patch it after every update.

Current state

shared/apm.md's import-schema exposes packages, app-id / private-key / owner / repositories, apps, and target — but not apm-version. Both apm-action steps (Pack and Restore) omit the apm-version input, so the CLI version falls through to the action's pinned default.

Proposed change

1. Add to import-schema:

   apm-version:
     type: string
     required: false
     description: >
       apm CLI version for apm-action to install (e.g. '0.20.0'). Omit to use
       the action's pinned default. Pin explicitly for reproducibility.

2. Thread it into both apm-action steps (they must match, so the pack and restore CLI versions can't skew):

   with:
     apm-version: ${{ github.aw.import-inputs.apm-version }}
     # ...existing inputs...

Consumers then set it cleanly in their import, with no vendored-file patching and no loss on gh aw update:

imports:
  - uses: shared/apm.md
    with:
      apm-version: '0.20.0'
      target: copilot
      packages:
        - example.ghe.com/<org>/<package>

Prior art

• shared/apm.md: support multiple GitHub Apps per workflow for multi-org private packages #983 (closed) added the apps: import input to shared/apm.md — precedent that the import schema is the right home for consumer-facing configuration, and that this kind of addition is accepted.
• Bump shared/apm.md to microsoft/apm-action@v1.4.2 (restore-mode workspace pollution fix) #902 (closed) bumped shared/apm.md to a newer microsoft/apm-action — shows the action/CLI version is maintained here today, but only as a hardcoded edit, not a consumer-settable input.
• [BUG] Links from inside skill bundle to other directories do not get rewritten #1625 (closed, PR fix(install): rewrite outbound relative links from skill bundles (closes #1625) #1657) — a skill-bundle link-rewriting fix that landed in a later apm release; representative of the CLI behavior changes consumers on the pinned default can't pick up without selecting the version.

Note on the action ref

The microsoft/apm-action@<tag> ref itself can't be parameterized the same way (gh-aw SHA-pins the literal uses: ref at compile time), so bumping the action still means editing the vendored file or pulling a newer upstream shared/apm.md. Exposing apm-version covers the common case — a newer CLI on the existing action — without that edit, since the action accepts the input regardless.

[github-actions]

Triage decision

defer-later

Proposed labels

area/ci-cd
type/feature
status/accepted
status/triaged

Milestone

null

Suggested next action

Open a PR against shared/apm.md that adds apm-version to the import-schema (optional string, no default) and threads ${{ github.aw.import-inputs.apm-version }} into both apm-action with: blocks.

Suggested issue comment

Thanks for the thorough write-up and for digging up the prior-art references (#983, #902, #1625) -- that context makes the case clearly.

This is accepted: `apm-version` is the right home for consumer-pinned CLI version selection, and the prior work in #983 confirms the import schema is the correct surface for this kind of addition. The problem statement is real -- hand-editing vendored files that get clobbered on `gh aw update` is exactly the friction this input removes.

The proposed change is bounded: one new optional key in `import-schema`, threaded into both `apm-action` `with:` blocks (Pack and Restore). The constraint you noted -- that the action ref itself cannot be parameterized -- is the right boundary to document.

Labelled `status/accepted` with no milestone (defer-later: clean scope, no active sprint slot). If you want to open a PR, the implementation is straightforward following the #983 pattern. Happy to review!

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The issue maps to a real user task: consumers who need a specific apm CLI version for reproducibility or to pick up a behavior fix are currently forced to hand-edit vendored workflow files -- a fragile workaround that breaks on gh aw update. Exposing apm-version as an optional import input follows the npm/pip mental model of explicit version pinning and aligns with how other import inputs work in shared/apm.md. The required: false design with the action's pinned default as fallback is the correct default-off ergonomic. The proposed YAML example in the issue body is well-formed and readable.

Supply Chain Security Expert -- Risk-Surface Reviewer

Exposing apm-version as an import input is a positive supply-chain property: it enables explicit version pinning for reproducibility. No new attack surface is introduced -- the input is passed to microsoft/apm-action, which validates version strings before use. No token handling or authentication changes. The area/ci-cd label is appropriate; no theme/security or theme/governance escalation needed.

OSS Growth Hacker -- Contributor-Tone Reviewer

anthonymastreanvae has NONE author_association -- first-time or low-interaction contributor. The issue is exceptionally well-structured: clear problem, proposed solution, YAML examples, prior-art citations, and honest constraint acknowledgement. The reply acknowledges the prior-art research specifically (mentioning #983, #902, #1625 by number), confirms acceptance, and ends with a concrete next step (open a PR following the #983 pattern). Warm but not condescending; treats the author as a capable contributor.

Python Architect -- Architecture Reviewer

Not activated -- the change is bounded to a single file (shared/apm.md), is additive (new optional key), and has direct precedent in #983. No cross-cutting design decision or new interface required.

Doc Writer -- Documentation Reviewer

The implementing PR should update the shared/apm.md inline documentation (import-schema description) and any guide that describes how to configure the shared workflow. The apm-usage/ skill resource may also need a note per repo Rule 4. No new doc pages required; the change is a minor additive update to existing references. area/docs-site is not added as a label since the doc work is minor and the issue is already infra-scoped.

APM CEO -- Triage Arbiter

This is a pure area/ci-cd change with no product-CLI surface implication -- the mega-theme exemption for pure infra issues applies (only area/ci-cd is relevant, no portability/security/governance product surface). The existing type/feature and status/accepted maintainer-applied labels are correct and are preserved. Adding area/ci-cd + status/triaged closes the label gap and the sweep loop. Defer-later with no milestone: clean scope, accepted, no active sprint slot. The +1 reaction confirms community interest; if the author wants to contribute a PR, the pattern from #983 is the right guide.

{
  "decision": "defer-later",
  "decision_detail": "",
  "theme": null,
  "areas": ["area/ci-cd"],
  "type": "type/feature",
  "status": "status/accepted",
  "priority": null,
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Open a PR against shared/apm.md adding apm-version to import-schema (optional string) and threading it into both apm-action with: blocks.",
  "comment_markdown": "Thanks for the thorough write-up and for digging up the prior-art references (#983, #902, #1625) -- that context makes the case clearly. This is accepted: apm-version is the right home for consumer-pinned CLI version selection, and the prior work in #983 confirms the import schema is the correct surface. The change is bounded: one new optional key in import-schema, threaded into both apm-action with: blocks. Labelled status/accepted with no milestone. If you want to open a PR, the implementation is straightforward following the #983 pattern. Happy to review!"
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · sonnet46 3.8M · ◷