ADO: full https:// URL with sub-path rejected by parser (shorthand and object form work)

[danielmeppiel]

Summary

DependencyReference.parse() rejects the natural full-URL form for an Azure DevOps repository with a sub-path:

https://dev.azure.com/<org>/<project>/_git/<repo>/<sub-path>

This is the URL ADO's browser shows. Users paste it straight into apm.yml and hit ValueError: Invalid Azure DevOps repository path. The shorthand form (dev.azure.com/<org>/<project>/_git/<repo>/<sub-path>) and the object form (git: <url> + path: <sub-path>) both work for the same dependency, so the failure mode is "the most natural URL is the only one that doesn't work."

Reproduction

from apm_cli.models.dependency.reference import DependencyReference

# WORKS (shorthand)
DependencyReference.parse("dev.azure.com/myorg/myproj/_git/myrepo/instructions/security#v2.0")

# WORKS (object form)
DependencyReference.parse_from_dict({
    "git": "https://dev.azure.com/myorg/myproj/_git/myrepo",
    "path": "instructions/security",
    "ref": "v2.0",
})

# FAILS - this is what users paste from their ADO browser tab
DependencyReference.parse("https://dev.azure.com/myorg/myproj/_git/myrepo/instructions/security")
# ValueError: Invalid Azure DevOps repository path: expected 'org/project/repo',
#   got 'myorg/myproj/_git/myrepo/instructions/security'

# Same failure with #ref appended
DependencyReference.parse("https://dev.azure.com/myorg/myproj/_git/myrepo/instructions/security#v2.0")

Full matrix exercised locally on main:

Shape	Result
dev.azure.com/<o>/<p>/_git/<r>	OK
dev.azure.com/.../<r>#v2.0	OK
dev.azure.com/.../<r>/<sub>	OK
dev.azure.com/.../<r>/<sub>#v2.0	OK
https://dev.azure.com/<o>/<p>/_git/<r>	OK
https://dev.azure.com/.../<r>#v2.0	OK
https://dev.azure.com/.../<r>/<sub>	FAIL
https://dev.azure.com/.../<r>/<sub>#v2.0	FAIL
Object form (any combination)	OK

Root cause (likely)

src/apm_cli/models/dependency/reference.py:602-610 strips the _git segment for ADO and then asserts a 3-segment path (org/project/repo). When the path includes a sub-path, the post-strip segment list is longer than 3 and the strict check fires before the virtual-path detection that handles the same case in the shorthand branch.

The shorthand branch handles this correctly (the OK rows above). The full-URL branch needs to either (a) defer the 3-segment check until after virtual-path detection, or (b) reuse whatever logic the shorthand branch already has.

Acceptance criteria

• All 8 URL shapes in the table above resolve correctly.
• Add a parameterized unit test in tests/unit/test_ado_path_structure.py covering all 8 shapes plus the 3 object-form variants exercised above.
• Verify behavior is identical for *.visualstudio.com legacy URLs.
• Update docs/src/content/docs/guides/dependencies.md to drop the "URL form not yet accepted" warning added in docs: clarify APM's role for skills, unify plugins-as-packages, add ADO sub-path examples, state stability #1127 once the fix lands.

Failing test (repro, ready to add to the suite)

import pytest
from apm_cli.models.dependency.reference import DependencyReference


@pytest.mark.parametrize("dep_str,expected_subpath,expected_ref", [
    # Shorthand - all currently pass
    ("dev.azure.com/myorg/myproj/_git/myrepo", None, None),
    ("dev.azure.com/myorg/myproj/_git/myrepo#v2.0", None, "v2.0"),
    ("dev.azure.com/myorg/myproj/_git/myrepo/instructions/security", "instructions/security", None),
    ("dev.azure.com/myorg/myproj/_git/myrepo/instructions/security#v2.0", "instructions/security", "v2.0"),
    # Full https - first two pass, last two FAIL today (this issue)
    ("https://dev.azure.com/myorg/myproj/_git/myrepo", None, None),
    ("https://dev.azure.com/myorg/myproj/_git/myrepo#v2.0", None, "v2.0"),
    ("https://dev.azure.com/myorg/myproj/_git/myrepo/instructions/security", "instructions/security", None),
    ("https://dev.azure.com/myorg/myproj/_git/myrepo/instructions/security#v2.0", "instructions/security", "v2.0"),
])
def test_ado_subpath_ref_combinations(dep_str, expected_subpath, expected_ref):
    dep = DependencyReference.parse(dep_str)
    assert dep.ado_organization == "myorg"
    assert dep.ado_project == "myproj"
    assert dep.ado_repo == "myrepo"
    assert dep.virtual_path == expected_subpath
    assert dep.is_virtual == (expected_subpath is not None)
    assert dep.reference == expected_ref

The first 6 rows pass on main. The last 2 rows fail with ValueError: Invalid Azure DevOps repository path.

User impact

Surfaced via user feedback on agent-asset distribution. They reported the dependency "could not get it to work (failed)" - this URL form is the most likely cause given how ADO's UI presents repo URLs. Workarounds exist (shorthand, object form) and are now documented in #1127, but the natural pasted URL should also work.

Related

• docs: clarify APM's role for skills, unify plugins-as-packages, add ADO sub-path examples, state stability #1127 (docs: ADO sub-path examples + warning that links here)

[github-actions]

Triage decision

accept

Proposed labels

theme/portability
area/lockfile
area/docs-site
type/bug
status/accepted
priority/high

Milestone

0.12.2 (next patch after v0.12.1 released 2026-05-03; maintainer: please confirm milestone number and assign)

Suggested next action

Fix DependencyReference.parse() to defer the 3-segment assertion until after virtual-path detection for the full-URL branch, add the parameterized test from the issue body, and update docs/src/content/docs/guides/dependencies.md to remove the warning added in #1127.

Suggested issue comment

Thanks for the detailed write-up and the ready-to-run failing test -- this makes the fix very straightforward to land.

Accepted as a `priority/high` bug fix targeting the next patch release. The root cause is confirmed: the full-URL branch in `DependencyReference.parse()` fires the 3-segment org/project/repo check before the virtual-path detection that the shorthand branch already handles correctly. The fix should make both branches reach the same logic path, so all 8 URL shapes in your matrix resolve identically.

Acceptance criteria from the issue:
- [x] All 8 URL shapes pass (shorthand, full-https, object form, with and without sub-path and ref)
- [ ] Parameterized unit test in `tests/unit/test_ado_path_structure.py` (failing test body is in the issue)
- [ ] Same behavior verified for `*.visualstudio.com` legacy URLs
- [ ] Warning removed from `docs/src/content/docs/guides/dependencies.md` (added in #1127)

The doc update in `docs/src/content/docs/guides/dependencies.md` is part of the required scope -- the warning added in #1127 exists specifically because this shape was broken, so it should be removed when the fix lands.

If you want to pick this up yourself, the failing test in the issue body is a great starting point. Otherwise it will be tracked for the next patch.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

This is a textbook "Recovery" failure: the most natural URL form -- what ADO's browser tab shows -- is the only variant that does not work. Users paste it into apm.yml and receive ValueError: Invalid Azure DevOps repository path with no hint of the correct alternative. The shorthand and object forms are valid workarounds but are not discoverable without reading docs. This directly violates the "Failure mode is the product" north star (every error should name what failed, why, and one concrete next action). The fix makes APM behave like pip install git+(redacted): accept the canonical URL the platform presents. The acceptance criteria matrix is thorough and the failing test is ready to add. Clear type/bug, priority/high for active user impact.

Supply Chain Security Expert -- Risk-Surface Reviewer

This issue touches DependencyReference.parse() in the dependency resolution pipeline, which warrants a close read. The proposed fix defers the 3-segment org/project/repo assertion until after virtual-path detection -- the same order the shorthand branch already uses. This is a parity fix, not a relaxation: the identity check still fires, just after the virtual-path split. No lockfile schema change, no download path change, no token or auth surface touched. No risk-surface implication. theme/security is NOT warranted. area/lockfile applies because dependency reference parsing feeds into lockfile resolution; this label replaces the non-taxonomy area/dependencies currently on the issue.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- author is a COLLABORATOR on microsoft/apm with deep prior context; tone-tuning for a first-time contributor is not needed.

Python Architect -- Architecture Reviewer

Not activated -- the fix is localized to one file (src/apm_cli/models/dependency/reference.py, lines 602-610) and the design is explicit: defer the 3-segment check until after virtual-path detection, matching the shorthand branch. No new interface, data model, or cross-cutting contract is introduced. The issue provides the root cause and two concrete fix strategies; no design doc is needed before code lands.

Doc Writer -- Documentation Reviewer

Doc work is integral: the issue explicitly requires removing the "URL form not yet accepted" warning from docs/src/content/docs/guides/dependencies.md that was added as a temporary acknowledgment in #1127. Adding area/docs-site as a secondary area label ensures the implementing PR is reminded. The suggested comment wording is clear and grounded in APM's dependency vocabulary; it names the doc update as part of the acceptance criteria rather than an afterthought, which is correct given the warning was added specifically because this shape was broken.

APM CEO -- Triage Arbiter

Straightforward accept at high priority. The bug has a confirmed repro, a located root cause, ready-to-run failing tests, and clear acceptance criteria. The fix is parity with the already-correct shorthand branch -- no new design needed. theme/portability applies because this broadens ADO URL support to the most natural form users encounter in the ADO browser UI, which is an adoption/portability concern. Active user feedback ("could not get it to work") and the v0.12.1 release yesterday both support targeting the next patch. The non-taxonomy label area/dependencies on the issue should be replaced with area/lockfile; note this for the maintainer.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": "theme/portability",
  "areas": ["area/lockfile", "area/docs-site"],
  "type": "type/bug",
  "status": "status/accepted",
  "priority": "priority/high",
  "preserved_labels": [],
  "milestone": "0.12.2",
  "next_action": "Fix DependencyReference.parse() to defer 3-segment assertion until after virtual-path detection, add the parameterized test from the issue body, and remove the docs warning added in #1127.",
  "comment_markdown": "Thanks for the detailed write-up and the ready-to-run failing test -- this makes the fix very straightforward to land.\n\nAccepted as a priority/high bug fix targeting the next patch release. The root cause is confirmed: the full-URL branch in DependencyReference.parse() fires the 3-segment org/project/repo check before the virtual-path detection that the shorthand branch already handles correctly. The fix should make both branches reach the same logic path, so all 8 URL shapes in your matrix resolve identically.\n\nAcceptance criteria from the issue:\n- All 8 URL shapes pass (shorthand, full-https, object form, with and without sub-path and ref)\n- Parameterized unit test in tests/unit/test_ado_path_structure.py (failing test body is in the issue)\n- Same behavior verified for *.visualstudio.com legacy URLs\n- Warning removed from docs/src/content/docs/guides/dependencies.md (added in #1127)\n\nThe doc update in docs/src/content/docs/guides/dependencies.md is part of the required scope -- the warning added in #1127 exists specifically because this shape was broken, so it should be removed when the fix lands.\n\nIf you want to pick this up yourself, the failing test in the issue body is a great starting point. Otherwise it will be tracked for the next patch."
}

---

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.

Note

🔒 Integrity filter blocked 41 items

The following items were blocked because they don't meet the GitHub integrity level.

• [FEATURE] Extended MCP Server Configuration in apm.yml #20 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• [FEATURE] Allow install to download and unpack a GitHub release automatically #514 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• [FEATURE] Skills from .well-known URIs #554 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• Feature: per-target agent frontmatter transformation during deployment #581 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• bug: apm run start picks wrong runtime — system PATH stub takes priority over APM-managed binary, codex v0.116+ incompatible with GitHub Models #605 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• [FEATURE] Add ability to specify a different configuration file name or path #612 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• bug: apm install plugin@marketplace validation bypasses registry proxy #615 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• [FEATURE] Renovate supporting apm.yml #639 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• Align CONTRIBUTING, Python formatting (Black/isort), and CI #645 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• [FEATURE] Copilot CLI user-scope instructions: can apm install -g write copilot-instructions.md #650 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• Marketplace add source parity with the Anthropic spec #676 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• [FEATURE] PEP 8 Support #690 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• [FEATURE] URL-based marketplace work Extension #692 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• [FEATURE] Create root AGENTS.md documenting all CI-enforced rules for coding agents #695 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• [FEATURE] Kiro Support #702 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• [FEATURE] Installation via NPM registry #732 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• ... and 25 more items

To allow these resources, lower min-integrity in your GitHub frontmatter:

tools:
  github:
    min-integrity: approved  # merged | approved | unapproved | none

Generated by Triage Panel · ● 909.8K · ◷