fix(install): surface custom port in generic host clone/ls-remote error by edenfunf · Pull Request #804 · microsoft/apm

Eden (edenfunf) · 2026-04-21T07:52:43Z

Description

The two is_generic error branches in github_downloader render the bare host in the "For private repositories on {host}" hint, dropping any custom port. Users on Bitbucket Datacenter (or any self-hosted host on a non-default port) see a diagnostic that hides the very detail they need to verify their git credential helper against:

For private repositories on bitbucket.corp.com, configure SSH keys or a git credential helper.

instead of:

For private repositories on bitbucket.corp.com:7999, configure SSH keys or a git credential helper.

Both branches now route through AuthResolver.classify_host(...).display_name, so the generic path shares port rendering with the adjacent ADO and auth branches (which already used build_error_context → host_info.display_name). This also means any future refinement to HostInfo.display_name (e.g. default-port normalisation, tracked in #797) propagates to these two call sites for free.

Scope-limited per the issue: no new signatures, no schema impact; only the two host_name = dep_host or "..." lines change. The "the target host" fallback is kept for the (unreachable-today but defensive) dep_host=None case, mirroring the dep_ref.port if dep_ref else None guard already used at the neighbouring auth call sites.

Fixes#798

Type of change

Bug fix
New feature
Documentation
Maintenance / refactor

Testing

Tested locally
All existing tests pass
Added tests for new functionality (if applicable)

New regression tests in tests/unit/test_generic_host_error_port.py cover both error branches with three shapes each: ssh custom port (Bitbucket DC 7999), https custom port (Bitbucket DC 7990), and a no-port control that guards against spurious : suffixes. Temporarily reverting the fix turns the four port-bearing assertions red with the exact bare-host string described in the issue, then green again once the fix is reapplied -- the tests bite on the regression they're named after.

Manual verification with ssh://git@bitbucket.nonexistent-host.example:7999/team/repo.git:

Failed to clone repository team/repo via SSH. ...
For private repositories on bitbucket.nonexistent-host.example:7999, configure SSH keys or a git credential helper.
APM delegates authentication to git for non-GitHub/ADO hosts.

pytest tests/unit -q → 4449 passed, 0 new failures. The three pre-existing failures in tests/test_github_downloader.py reproduce on origin/main without this patch and are unrelated.

The two is_generic error branches in github_downloader rendered the bare host, dropping ``:{port}`` from the ``"For private repositories on {host}"`` hint. Users on Bitbucket Datacenter (or any self-hosted host using a non-default port) saw a diagnostic that hid the very detail they needed to verify their git credential helper against. Route both branches through ``AuthResolver.classify_host(...).display_name`` so the generic path shares port rendering with the adjacent ADO and auth branches (which already used ``build_error_context`` -> ``host_info.display_name``). Keep the ``"the target host"`` fallback for the (unreachable-today but defensive) ``dep_host=None`` case, and mirror the ``dep_ref.port if dep_ref else None`` guard used at the neighbouring call sites. Scope-limited: no new signatures, no schema impact; only the two ``host_name = dep_host or "..."`` lines change. Regression tests in tests/unit/test_generic_host_error_port.py cover both call sites with ssh/https custom port and a no-port control. Closesmicrosoft#798

Copilot

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR fixes generic git-host error hints so they include custom ports (e.g., bitbucket.corp.com:7999) when clone or ls-remote fails, and adds regression tests to prevent future regressions.

Changes:

Update generic-host error handling in GitHubPackageDownloader to use AuthResolver.classify_host(...).display_name (includes port).
Add unit tests covering both _clone_with_fallback and list_remote_refs generic error branches for SSH/HTTPS custom ports and no-port control cases.

Show a summary per file

File	Description
`src/apm_cli/deps/github_downloader.py`	Ensures generic-host private-repo hint renders `host:port` via `HostInfo.display_name`.
`tests/unit/test_generic_host_error_port.py`	Adds regression coverage to assert port rendering in both generic error paths.

Copilot's findings

Files reviewed: 2/2 changed files
Comments generated: 4

…ort fix + CHANGELOG Code changes: - Simplify port guard in ``list_remote_refs``' is_generic branch: ``port=dep_ref.port if dep_ref else None`` -> ``port=dep_ref.port``. ``list_remote_refs(self, dep_ref: DependencyReference)`` has no Optional on ``dep_ref`` and L1026 already dereferences it unconditionally, so the guard implied a nullability contract that does not exist on this code path. The clone-path ternary at L866 stays -- ``_clone_with_fallback``'s L715 does treat ``dep_ref`` as optional, so the guard is load-bearing there. - Use integer exit code 128 instead of the string "failed" in the clone test fixture. Matches the adjacent ls-remote fixture (L124) and ``test_list_remote_refs.py``; GitPython's ``GitCommandError`` status argument is a shell exit code, so an int models real failures more faithfully than a placeholder string. Deliberately not adopted (rationale recorded for the next reviewer): - No ``_generic_host_display_name(dep_host, dep_ref)`` helper: the single source of truth for port rendering already lives on ``HostInfo.display_name``; a private helper would only relocate the two-line ``classify_host(...).display_name`` call without adding defence against drift. Future refinements (e.g. the default-port normalisation tracked in microsoft#797, if it lands on ``HostInfo.__post_init__``) propagate to both call sites through ``display_name`` regardless of whether the call sites share a wrapper. microsoft#798 was scoped explicitly as a two-line change on each branch. - No ``@pytest.mark.parametrize`` over the six regression cases: each test has a self-documenting name (``test_ssh_custom_port_surfaces_in_error``, ``test_no_port_renders_bare_host``, etc.) which keeps failure triage grep-friendly. Clone and ls-remote branches use different mocks (``Repo.clone_from`` vs ``git.cmd.Git``), and the no-port variant asserts a negative property, so the six-case matrix does not compress cleanly into a single parametrize table without either bifurcating the parametrize or reducing assertion clarity. CHANGELOG: add a ``### Fixed`` entry under ``[Unreleased]`` documenting the ``host:port`` surfacing in the generic clone / ls-remote error branches.

github-actions · 2026-04-22T23:57:26Z

APM Review Panel Verdict

Disposition: REQUEST_CHANGES -- one required action before merge (CHANGELOG entry); fix itself is clean and ready.

Per-persona findings

Python Architect: No architectural concerns. The fix follows the exact pattern already used by the adjacent ADO branches (build_error_context -> host_info.display_name). Using a real AuthResolver in _make_downloader() is the right call here: the regression is specifically about classify_host -> HostInfo.display_name propagating port, so mocking the resolver would defeat the test. The dep_host is None fallback ("the target host") is correctly preserved for the defensive unreachable case. Scope is minimal and well-justified in the PR description. No abstraction debt introduced.

CLI Logging Expert: Error message improvement is clean and consistent. Both _clone_with_fallback (~L920) and list_remote_refs (~L1098) now produce host:port via display_name rather than bare host. The rendered string "For private repositories on {host_name}, configure SSH keys or a git credential helper." is unchanged structurally -- only the host_name value improves. Consistent with how the ADO branch already routes through build_error_context -> host_info.display_name. No CommandLogger or DiagnosticCollector changes needed; this is a targeted error-string fix. No concerns.

DevX UX Expert: Real ergonomic win for Bitbucket Datacenter and any self-hosted server on a non-standard port. Before this fix, a user seeing "For private repositories on bitbucket.corp.com" could not confirm whether their git credential helper was configured for the right endpoint -- the port is what differentiates bitbucket.corp.com:7999 from default HTTPS on the same host. The fix makes the error actionable: users can now directly compare the displayed host:port to their credential helper config. host:port format is the industry standard for non-default ports (used by SSH config, Docker, every CLI tool). No command surface or flag changes; no docs update needed for a pure error-message fix.

Supply Chain Security Expert: No security surface changes. classify_host is a @staticmethod with no I/O, no network calls, no token handling, and no side effects -- it pattern-matches the hostname and returns a frozen HostInfo dataclass. dep_host is already in scope (parsed from dep_ref.host), and dep_ref.port is an integer parsed at URL-parse time. The only new behavior is feeding these already-validated values into a pure classification function and reading back display_name. No new path, no new auth surface, no new token scope. No concerns.

Auth Expert: auth_resolver.classify_host(dep_host, port=...) is the intended public API for exactly this purpose -- host classification to drive display and credential selection. The call is appropriate and isolated to the error-path; it runs after the clone/ls-remote has already failed. No credential or token logic is touched.

OSS Growth Hacker: Bitbucket Datacenter adoption is a real enterprise wedge. Self-hosted Git servers on custom ports are ubiquitous in regulated industries (finance, healthcare, defense) -- the exact cohort APM's enterprise story needs. This fix removes a concrete papercut that would cause a support ticket or a dropped eval. No conversion surface changes needed; the fix speaks for itself in release notes. Side-channel to CEO: recommend leading with the "Bitbucket DC" framing in CHANGELOG and release notes -- it names a concrete product, which converts better than "custom port" in searches.

CEO arbitration

This is a clean, well-scoped bug fix that closes a real user-reported issue (#798) with appropriate test coverage (6 cases across both error branches: SSH custom port, HTTPS custom port, and no-port control for each). The implementation is consistent with the existing codebase pattern -- no new abstractions, no signature changes, no schema impact. The PR is merge-ready on the technical merits. The only gap is a missing CHANGELOG.md entry, which is required by repo convention for every PR that changes code. The Unreleased section is open; this belongs under ### Fixed. One line unblocks the merge.

Required actions before merge

Add a CHANGELOG entry under ## [Unreleased] > ### Fixed in CHANGELOG.md. Suggested text:

- `apm install` / `apm run`: generic-host error hints now render `host:port` instead of bare `host` for self-hosted servers (e.g. Bitbucket Datacenter) on non-default ports. Fixes #798 (#804)

Optional follow-ups

The dl.auth_resolver._cache.clear() line in _make_downloader() reaches into a private attribute. Consider whether AuthResolver should expose a clear_cache() test helper; low priority, no impact here.
Issue [FOLLOW-UP #788] Normalise default-scheme ports (443/80/22) on DependencyReference / HostInfo #797 (default-port normalization in HostInfo.display_name) is referenced in the PR -- once that lands, both call sites updated here will inherit the normalization for free. No action needed now.
_make_downloader() is a self-contained factory used by both test classes. If further generic-host tests are added, consider promoting it to a conftest.py fixture in the tests/unit/ subtree.

Generated by PR Review Panel for issue #804 · ● 521.7K · ◷

* chore: prepare v0.9.2 release Bumps version to 0.9.2 and finalizes CHANGELOG with one-line summaries for each PR merged since 0.9.1. Highlights: - ADO AAD bearer-token auth (#856) - Governance Guide + enterprise docs IA refactor (#851, #858) - Merge Gate orchestrator + single-authority aggregation (#865, #867) - Landing + first-package docs rewrite (#855, #866) - gh-aw imports migration (#864) - Custom-port surfacing fix (#804) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * ci: simplify merge-gate to single pull_request trigger The dual-trigger pattern (pull_request + pull_request_target with concurrency cancel-in-progress) shipped in #865 was over-engineered. It produced TWO 'gate' check-runs per SHA -- one SUCCESS, one CANCELLED -- and branch protection's status-check rollup treats CANCELLED as failure, so PRs were silently BLOCKED unless an admin overrode (which masked the bug on #867). GitHub Actions has no primitive for 'either of these events succeeded'. World-class OSS projects (kubernetes, rust, deno, next.js) accept this and use a single trigger. The cost: a dropped 'pull_request' webhook (rare; observed once on PR #856) requires manual recovery. Recovery paths now documented at top of file: - push empty commit - gh workflow run merge-gate.yml -f pr_number=NNN - close + reopen PR Replaces the dual-trigger + bootstrap-fetch dance with a clean two-job flow: resolve-sha (handles workflow_dispatch input or PR head) then gate (sparse checkout + run script). Same script, same exit codes, same EXPECTED_CHECKS env. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * ci: collapse merge-gate into a single job (one check-run in PR UI) The two-job split (resolve-sha + gate) created two visible check-runs. Inlining the SHA resolution as a step within the gate job leaves only one check-run -- 'Merge Gate / gate' -- on the PR. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…or (#804) * fix(install): surface custom port in generic host clone/ls-remote error The two is_generic error branches in github_downloader rendered the bare host, dropping ``:{port}`` from the ``"For private repositories on {host}"`` hint. Users on Bitbucket Datacenter (or any self-hosted host using a non-default port) saw a diagnostic that hid the very detail they needed to verify their git credential helper against. Route both branches through ``AuthResolver.classify_host(...).display_name`` so the generic path shares port rendering with the adjacent ADO and auth branches (which already used ``build_error_context`` -> ``host_info.display_name``). Keep the ``"the target host"`` fallback for the (unreachable-today but defensive) ``dep_host=None`` case, and mirror the ``dep_ref.port if dep_ref else None`` guard used at the neighbouring call sites. Scope-limited: no new signatures, no schema impact; only the two ``host_name = dep_host or "..."`` lines change. Regression tests in tests/unit/test_generic_host_error_port.py cover both call sites with ssh/https custom port and a no-port control. Closes#798 * fix(install): address review feedback on #798 generic-host port fix + CHANGELOG Code changes: - Simplify port guard in ``list_remote_refs``' is_generic branch: ``port=dep_ref.port if dep_ref else None`` -> ``port=dep_ref.port``. ``list_remote_refs(self, dep_ref: DependencyReference)`` has no Optional on ``dep_ref`` and L1026 already dereferences it unconditionally, so the guard implied a nullability contract that does not exist on this code path. The clone-path ternary at L866 stays -- ``_clone_with_fallback``'s L715 does treat ``dep_ref`` as optional, so the guard is load-bearing there. - Use integer exit code 128 instead of the string "failed" in the clone test fixture. Matches the adjacent ls-remote fixture (L124) and ``test_list_remote_refs.py``; GitPython's ``GitCommandError`` status argument is a shell exit code, so an int models real failures more faithfully than a placeholder string. Deliberately not adopted (rationale recorded for the next reviewer): - No ``_generic_host_display_name(dep_host, dep_ref)`` helper: the single source of truth for port rendering already lives on ``HostInfo.display_name``; a private helper would only relocate the two-line ``classify_host(...).display_name`` call without adding defence against drift. Future refinements (e.g. the default-port normalisation tracked in #797, if it lands on ``HostInfo.__post_init__``) propagate to both call sites through ``display_name`` regardless of whether the call sites share a wrapper. #798 was scoped explicitly as a two-line change on each branch. - No ``@pytest.mark.parametrize`` over the six regression cases: each test has a self-documenting name (``test_ssh_custom_port_surfaces_in_error``, ``test_no_port_renders_bare_host``, etc.) which keeps failure triage grep-friendly. Clone and ls-remote branches use different mocks (``Repo.clone_from`` vs ``git.cmd.Git``), and the no-port variant asserts a negative property, so the six-case matrix does not compress cleanly into a single parametrize table without either bifurcating the parametrize or reducing assertion clarity. CHANGELOG: add a ``### Fixed`` entry under ``[Unreleased]`` documenting the ``host:port`` surfacing in the generic clone / ls-remote error branches. --------- Co-authored-by: Daniel Meppiel <51440732+danielmeppiel@users.noreply.github.com>

* chore: prepare v0.9.2 release Bumps version to 0.9.2 and finalizes CHANGELOG with one-line summaries for each PR merged since 0.9.1. Highlights: - ADO AAD bearer-token auth (#856) - Governance Guide + enterprise docs IA refactor (#851, #858) - Merge Gate orchestrator + single-authority aggregation (#865, #867) - Landing + first-package docs rewrite (#855, #866) - gh-aw imports migration (#864) - Custom-port surfacing fix (#804) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * ci: simplify merge-gate to single pull_request trigger The dual-trigger pattern (pull_request + pull_request_target with concurrency cancel-in-progress) shipped in #865 was over-engineered. It produced TWO 'gate' check-runs per SHA -- one SUCCESS, one CANCELLED -- and branch protection's status-check rollup treats CANCELLED as failure, so PRs were silently BLOCKED unless an admin overrode (which masked the bug on #867). GitHub Actions has no primitive for 'either of these events succeeded'. World-class OSS projects (kubernetes, rust, deno, next.js) accept this and use a single trigger. The cost: a dropped 'pull_request' webhook (rare; observed once on PR #856) requires manual recovery. Recovery paths now documented at top of file: - push empty commit - gh workflow run merge-gate.yml -f pr_number=NNN - close + reopen PR Replaces the dual-trigger + bootstrap-fetch dance with a clean two-job flow: resolve-sha (handles workflow_dispatch input or PR head) then gate (sparse checkout + run script). Same script, same exit codes, same EXPECTED_CHECKS env. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * ci: collapse merge-gate into a single job (one check-run in PR UI) The two-job split (resolve-sha + gate) created two visible check-runs. Inlining the SHA resolution as a step within the gate job leaves only one check-run -- 'Merge Gate / gate' -- on the PR. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Eden (edenfunf) requested review from Daniel Meppiel (danielmeppiel) and Sergio Sisternes (sergio-sisternes-epam) as code owners April 21, 2026 07:52

Daniel Meppiel (danielmeppiel) requested a review from Copilot April 21, 2026 18:24

Merge branch 'main' into fix/clone-error-port-display
f9dd0f5

Copilotstarted reviewing on behalf of Daniel Meppiel (danielmeppiel)April 21, 2026 18:30 View session

CopilotAI reviewed Apr 21, 2026
View reviewed changes

Comment threadsrc/apm_cli/deps/github_downloader.py
Comment threadsrc/apm_cli/deps/github_downloader.py
Comment threadtests/unit/test_generic_host_error_port.py Outdated
Comment threadtests/unit/test_generic_host_error_port.py

Eden (edenfunf)and others added 2 commits April 22, 2026 19:42

Merge branch 'main' into fix/clone-error-port-display
afbc529

Daniel Meppiel (danielmeppiel) added the panel-review Trigger the apm-review-panel gh-aw workflow label Apr 22, 2026

Daniel Meppiel (danielmeppiel) merged commit 5b996a3 into microsoft:mainApr 23, 2026
20 checks passed

This was referenced Apr 23, 2026
[docs] Update documentation for features from 2026-04-23 #862
Closed
chore: prepare v0.9.2 release #868
Merged

Navigation Menu

Uh oh!

fix(install): surface custom port in generic host clone/ls-remote error - #804

fix(install): surface custom port in generic host clone/ls-remote error#804
Daniel Meppiel (danielmeppiel) merged 4 commits into
microsoft:mainfrom
edenfunf:fix/clone-error-port-display

Eden (edenfunf) commented Apr 21, 2026

Uh oh!

CopilotAI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actionsBot commented Apr 22, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

Eden (edenfunf) commented Apr 21, 2026

Description

Type of change

Testing

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actionsBot commented Apr 22, 2026

APM Review Panel Verdict

Per-persona findings

CEO arbitration

Required actions before merge

Optional follow-ups

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants