[docs] Update documentation for features from 2026-04-14#699
[docs] Update documentation for features from 2026-04-14#699danielmeppiel wants to merge 2 commits intomainfrom
Conversation
- Add CHANGELOG entry for PR #653 (HTTPS fallback after SSH timeout) - Add troubleshooting section in installation.md for corporate firewall SSH issues - Add troubleshooting row in skills/apm-usage/troubleshooting.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
danielmeppiel
added
automation
documentation
There was a problem hiding this comment.
Pull request overview
This PR updates end-user documentation to cover the recent apm install behavior change where SSH clone attempts are bounded by a timeout and automatically fall back to HTTPS on networks that block port 22.
Changes:
- Add an Unreleased changelog entry for #653 describing the SSH-timeout-to-HTTPS fallback behavior.
- Add a new troubleshooting section in the installation docs explaining the scenario and how to force HTTPS.
- Extend the apm-usage troubleshooting skill table with a new row for SSH-blocked corporate networks.
Show a summary per file
| File | Description |
|---|---|
packages/apm-guide/.apm/skills/apm-usage/troubleshooting.md |
Adds a troubleshooting row describing the SSH timeout and automatic HTTPS retry, plus a hint to force HTTPS. |
docs/src/content/docs/getting-started/installation.md |
Adds a dedicated troubleshooting section for corporate networks that block SSH (port 22), including HTTPS forcing and debug guidance. |
CHANGELOG.md |
Adds an Unreleased bullet for #653 under Fixed. |
Copilot's findings
- Files reviewed: 3/3 changed files
- Comments generated: 2
| - Pin codex setup to `rust-v0.118.0` for security and reproducibility; update config to `wire_api = "responses"` (#663) | ||
| - Propagate headers and environment variables through OpenCode MCP adapter with defensive copies to prevent mutation (#622) | ||
| - Fix `apm install` hanging indefinitely when corporate firewalls silently drop SSH packets by setting `GIT_SSH_COMMAND` with `ConnectTimeout=30` (#652) | ||
| - Fix `apm install` falling back to HTTPS after SSH times out so installs complete on networks that block port 22 (#653) |
There was a problem hiding this comment.
The new changelog bullet reads like the bug was that apm install falls back to HTTPS, but the issue being fixed is that it previously did not fall back after the SSH timeout. Consider rephrasing to make the problem statement unambiguous (e.g., "Fix apm install not falling back to HTTPS after SSH times out ...").
| - Fix `apm install` falling back to HTTPS after SSH times out so installs complete on networks that block port 22 (#653) | |
| - Fix `apm install` not falling back to HTTPS after SSH times out so installs complete on networks that block port 22 (#653) |
|
|
||
| ### `apm install` hangs or times out on corporate networks (SSH blocked) | ||
|
|
||
| Some corporate firewalls silently drop SSH packets, causing `apm install` to stall indefinitely when APM tries to clone a dependency over SSH. |
There was a problem hiding this comment.
This paragraph says corporate firewalls cause apm install to "stall indefinitely" when cloning over SSH, but the documented behavior in the next paragraph (and the underlying fix) is that SSH now fails fast via ConnectTimeout=30 and then falls back to HTTPS. Please reword to reflect current behavior (e.g., "could hang" historically, or "may stall for up to ~30 seconds before falling back"), so the troubleshooting guidance is internally consistent and accurate for the current release.
| Some corporate firewalls silently drop SSH packets, causing `apm install` to stall indefinitely when APM tries to clone a dependency over SSH. | |
| Some corporate firewalls silently drop SSH packets, which can make `apm install` appear stalled for up to about 30 seconds while APM tries to clone a dependency over SSH. |
sergio-sisternes-epam
left a comment
sergio-sisternes-epam
left a comment
There was a problem hiding this comment.
Good docs addition -- covers the SSH timeout/HTTPS fallback clearly with actionable guidance.
Two minor wording nits (both already flagged by Copilot reviewer, I agree with its suggestions):
- CHANGELOG line 20: "falling back" reads like fallback is the bug. Should be "not falling back" per Copilot's suggestion.
- installation.md line 154: "stall indefinitely" contradicts the 30s timeout described immediately below. Suggest "appear stalled for up to ~30 seconds" per Copilot's suggestion.
Neither is blocking -- approve as-is, can be fixed in a follow-up or before merge.
Documentation Updates - 2026-04-14
This PR updates the documentation based on features merged in the last 24 hours.
Features Documented
apm installon networks that block port 22 (from Enable SSH timeout to fallback to HTTP. #653)Changes Made
CHANGELOG.mdto add an entry for PR Enable SSH timeout to fallback to HTTP. #653 (HTTPS fallback after SSH connection timeout)apm install hangs or times out on corporate networks (SSH blocked)indocs/src/content/docs/getting-started/installation.mdexplaining the automatic SSH-to-HTTPS fallback and how to force HTTPS via the dependency URL prefixpackages/apm-guide/.apm/skills/apm-usage/troubleshooting.mdcovering the SSH firewall scenarioMerged PRs Referenced
fix-apm-install)apm installhanging indefinitely when corporate firewalls silently drop SSH packets (setGIT_SSH_COMMANDConnectTimeout=30; already documented, referenced for context)Notes
The CHANGELOG already contained the PR #652 entry. PR #653 builds directly on top of it by ensuring that after the SSH connection times out (in 30 s),
_clone_with_fallbackcontinues to Method 3 (standard HTTPS) rather than surfacing the SSH error immediately. The new documentation covers both behaviors together from a user perspective.