feat: ADO marketplace support (marketplace.yml with Azure DevOps repos)

[sergio-sisternes-epam]

Summary

apm marketplace build currently assumes owner/repo as the package source format (enforced by SOURCE_RE in yml_schema.py). Azure DevOps repositories use a 3-part path (org/project/_git/repo) which doesn't fit this schema.

Context

This came up during the investigation for #1008 (GHE support). While RefResolver and build_https_clone_url() now work for any GITHUB_HOST value, ADO has structural differences that require dedicated support:

1. URL structure: ADO repos use https://dev.azure.com/{org}/{project}/_git/{repo} -- the 3-part path doesn't fit owner/repo
2. Schema validation: SOURCE_RE = r"^[^/]+/[^/]+$" in yml_schema.py only allows 2-segment paths
3. Metadata API: ADO uses a different REST API (/_apis/git/repositories/) than GitHub
4. Authentication: ADO uses ADO_APM_PAT or az CLI, not GITHUB_APM_PAT

Scope

• Extend SOURCE_RE to accept ADO-style 3-part paths (or add host field to marketplace.yml package entries)
• Add ADO URL construction for git ls-remote
• Add ADO metadata fetch via ADO REST API
• Wire ADO auth (ADO_APM_PAT / az CLI) into the marketplace builder
• Tests and documentation

Related

• [BUG] apm marketplace build fails for GitHub Enterprise Server repositories #1008 -- GHE marketplace support (landed)
• src/apm_cli/utils/github_host.py -- build_ado_https_clone_url() already exists
• src/apm_cli/core/auth.py -- AuthResolver already supports ADO hosts

[github-actions]

Triage decision

needs-design

Proposed labels

theme/governance
area/marketplace
area/enterprise
area/docs-site
type/feature
status/needs-design

Milestone

null

Suggested next action

Drop a comment here with the proposed marketplace.yml schema shape -- even a short YAML snippet showing the new host field (or the extended source format) is enough to unblock design alignment before a PR opens.

Suggested issue comment

Thanks for the well-structured write-up, @sergio-sisternes-epam. ADO marketplace support is a natural and well-motivated follow-on to the GHE work in #1008, and the existing infrastructure -- `build_ado_https_clone_url()` and `AuthResolver` ADO support -- gives us a solid foundation to build on.

Before a PR opens, one design question needs to be settled:

**Schema shape**: the issue proposes two options -- extend `SOURCE_RE` to accept 3-part ADO paths (`org/project/_git/repo`), or add a `host` field to `marketplace.yml` package entries. The `host` field approach is architecturally cleaner: it is explicit, backward-compatible with existing `owner/repo` entries, and extensible to future registry types. That is the direction the panel recommends, but the choice should be documented and agreed on before code lands.

The design note should cover three things:
1. The `marketplace.yml` schema change -- field name, format, and backward compatibility with existing entries
2. The ADO metadata client interface -- how it mirrors the GitHub metadata path inside the marketplace builder
3. Auth routing -- how the builder detects ADO vs GitHub and selects `ADO_APM_PAT` / `az` CLI vs `GITHUB_APM_PAT`

One implementation note for when work begins: the 3-part ADO path is a new input surface. Use `validate_path_segments()` from `src/apm_cli/utils/path_security.py` at parse time, and route all credential resolution through `AuthResolver` rather than any ad-hoc token handling.

Once the schema is settled, the scope you outlined -- schema, URL construction, ADO metadata API, auth wiring, tests, docs -- is exactly right. An `area/docs-site` label is added here as a reminder that the implementing PR will need to update the marketplace.yml reference and add an enterprise/ADO configuration guide.

To move this forward: drop a comment with the proposed schema (a YAML snippet of the new `marketplace.yml` format is enough), and we can validate it before work begins.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

Clear enterprise user need: APM teams on Azure DevOps are locked out of apm marketplace build today because SOURCE_RE enforces GitHub-style owner/repo only. This is a direct follow-on to GHE support (#1008) and aligns with APM's multi-registry positioning -- the same way npm and pip support multiple registries, APM should support multiple source hosting platforms. The author correctly decomposed the work into four orthogonal items (schema, URL, metadata, auth) and noted that existing infrastructure reduces implementation risk. Real surface, well-scoped, no framing issues.

Supply Chain Security Expert -- Risk-Surface Reviewer

Three P/G/S surfaces: (1) Auth -- ADO_APM_PAT / az CLI must route through AuthResolver, not ad-hoc token handling; (2) URL/path parsing -- the 3-part ADO path is a new injection surface that requires validate_path_segments() from src/apm_cli/utils/path_security.py before resolution; (3) Metadata API -- ADO REST responses must be sanitized before use. The governance angle dominates: ADO is an enterprise platform with organizational auth and tenant-scoped repos, which extends APM's trust model into a new enterprise perimeter. theme/governance is required; area/enterprise is warranted as a secondary area. No immediate vulnerability in the request itself, but the implementation must be reviewed for auth scoping and path traversal.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- author is a COLLABORATOR who has already landed GHE work (#1008); contributor warmth or pointer-set tuning for a new contributor would not meaningfully change the reply.

Python Architect -- Architecture Reviewer

The blocking design question is the schema shape: extend SOURCE_RE to accept 3-part paths vs add a host field to marketplace.yml package entries. Option A (regex extension) is ambiguous and does not generalize cleanly; Option B (explicit host field) is backward-compatible, explicit, and extensible to future registry types -- the issue author already hints at Option B. This is a schema contract change touching yml_schema.py, the marketplace builder's host-detection logic, and the new ADO metadata client interface. The cross-cutting impact is bounded (marketplace pipeline + auth routing), not repo-wide, so a full architecture spec is not required -- a short design note settling the schema shape and the metadata client interface is the gate. Recommend status/needs-design until that note is posted and agreed on.

Doc Writer -- Documentation Reviewer

Docs work is explicitly in scope (the issue lists "Tests and documentation"). The implementing PR will need: (1) marketplace.yml reference updated with the new host field syntax; (2) an enterprise/ADO configuration guide under docs/src/content/docs/enterprise/ or a new marketplace guide; (3) auth configuration docs for ADO_APM_PAT / az CLI. area/docs-site rides as a secondary label to remind the implementing PR. Suggested comment language is grounded in APM's established vocabulary ("marketplace", "package source", "enterprise") and does not introduce new terminology.

APM CEO -- Triage Arbiter

Direction is clearly in scope and the foundation is solid -- auth and URL builder already exist from prior work. The enterprise governance angle is genuine: ADO teams are locked out of APM marketplaces today, which directly harms adoption in the enterprise segment where APM's governance story is strongest. Security review correctly flags path-parsing and auth-routing as implementation discipline items, not design blockers. Python Architect is right that the schema shape (host field vs regex) must be settled before code lands -- this is a one-design-note gate, not a full architecture redesign. Decision: needs-design. No milestone (needs-design is milestone-free); once the schema note lands and is agreed, this is a natural 0.10.0 candidate for a contributor-driven PR.

{
  "decision": "needs-design",
  "decision_detail": "The marketplace.yml schema shape (host field vs extended SOURCE_RE) must be settled before code lands; see suggested comment for the three required design note items.",
  "theme": "theme/governance",
  "areas": ["area/marketplace", "area/enterprise", "area/docs-site"],
  "type": "type/feature",
  "status": "status/needs-design",
  "priority": null,
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Drop a comment with the proposed marketplace.yml schema shape (a YAML snippet is enough) to unblock design alignment before a PR opens.",
  "comment_markdown": "Thanks for the well-structured write-up, @sergio-sisternes-epam. ADO marketplace support is a natural and well-motivated follow-on to the GHE work in #1008, and the existing infrastructure -- `build_ado_https_clone_url()` and `AuthResolver` ADO support -- gives us a solid foundation to build on.\n\nBefore a PR opens, one design question needs to be settled:\n\n**Schema shape**: the issue proposes two options -- extend `SOURCE_RE` to accept 3-part ADO paths (`org/project/_git/repo`), or add a `host` field to `marketplace.yml` package entries. The `host` field approach is architecturally cleaner: it is explicit, backward-compatible with existing `owner/repo` entries, and extensible to future registry types. That is the direction the panel recommends, but the choice should be documented and agreed on before code lands.\n\nThe design note should cover three things:\n1. The `marketplace.yml` schema change -- field name, format, and backward compatibility with existing entries\n2. The ADO metadata client interface -- how it mirrors the GitHub metadata path inside the marketplace builder\n3. Auth routing -- how the builder detects ADO vs GitHub and selects `ADO_APM_PAT` / `az` CLI vs `GITHUB_APM_PAT`\n\nOne implementation note for when work begins: the 3-part ADO path is a new input surface. Use `validate_path_segments()` from `src/apm_cli/utils/path_security.py` at parse time, and route all credential resolution through `AuthResolver` rather than any ad-hoc token handling.\n\nOnce the schema is settled, the scope you outlined -- schema, URL construction, ADO metadata API, auth wiring, tests, docs -- is exactly right. An `area/docs-site` label is added here as a reminder that the implementing PR will need to update the marketplace.yml reference and add an enterprise/ADO configuration guide.\n\nTo move this forward: drop a comment with the proposed schema (a YAML snippet of the new `marketplace.yml` format is enough), and we can validate it before work begins."
}

---

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 for issue #1010 · ● 547.5K · ◷