Skip to content

[docs] Update documentation for features from 2026-04-14 #699

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
danielmeppiel wants to merge 2 commits into
base: main
Choose a base branch
from
+20 −0
Open

[docs] Update documentation for features from 2026-04-14 #699

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6951c3c
docs: document SSH timeout + HTTPS fallback from PR #653
Apr 14, 2026
37a0a35
Merge branch 'main' into docs/update-for-pr-653-7522a8e50ded4f02
sergio-sisternes-epam Apr 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- 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)
Copy link

Copilot AI Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 ...").

Suggested change
- 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)

Copilot uses AI. Check for mistakes.
- Fix `apm compile --target claude` silently skipping dependency instructions stored in `.github/instructions/` (#631)

### Changed
Expand Down
18 changes: 18 additions & 0 deletions docs/src/content/docs/getting-started/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -149,6 +149,24 @@ mkdir -p ~/bin

See [Authentication -- Troubleshooting](../authentication/#troubleshooting) for token setup, SSO authorization, and diagnosing auth failures.

### `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.
Copy link

Copilot AI Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
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.

Copilot uses AI. Check for mistakes.

APM automatically sets a 30-second SSH connection timeout (`GIT_SSH_COMMAND` with `-o ConnectTimeout=30`) and falls back to HTTPS when the SSH attempt fails. If installs are still slow, you can force HTTPS clones by prepending the dependency URL with `https://`:

```yaml
# apm.yml
dependencies:
- https://github.com/org/repo
```

If the problem persists, set `APM_DEBUG=1` for detailed clone diagnostics:

```bash
APM_DEBUG=1 apm install
```

### File access errors on Windows (antivirus / endpoint protection)

If `apm install` fails with `The process cannot access the file because it is being used by another process`, your antivirus or endpoint protection software is likely scanning temp files during installation.
Expand Down
1 change: 1 addition & 0 deletions packages/apm-guide/.apm/skills/apm-usage/troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

| Problem | Fix |
|---------|-----|
| `apm install` hangs or stalls (SSH blocked by firewall) | APM now times out SSH after 30 seconds and retries over HTTPS automatically. To force HTTPS always, prefix the dependency URL with `https://` in `apm.yml`. Use `APM_DEBUG=1` for clone diagnostics. |
| `apm: command not found` | Install APM: `curl -sSL https://aka.ms/apm-unix \| sh` (macOS/Linux) or `irm https://aka.ms/apm-windows \| iex` (Windows). Ensure `/usr/local/bin` is in `$PATH`. |
| Authentication errors (401/403) | Set the correct token. Run `apm install --verbose` to see which token source is used. See [Authentication](./authentication.md). |
| File collision on install | A local file conflicts with a dependency file. Use `--force` to overwrite, or rename the local file. |
Expand Down
Loading