Merge branch 'main' into fix/preserve-ssh-url-bitbucket-datacenter

Author: edenfunf

CHANGELOG.md

@@ -17,7 +17,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Preserve `ssh://` dependency URLs with custom ports for Bitbucket Datacenter repositories instead of silently falling back to HTTPS (#661)
 - 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 compile --target claude` silently skipping dependency instructions stored in `.github/instructions/` (#631)
+
 ### Changed
 
 - `apm marketplace browse/search/add/update` now route through the registry proxy when `PROXY_REGISTRY_URL` is set; `PROXY_REGISTRY_ONLY=1` blocks direct GitHub API calls (#506)
@@ -454,7 +456,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
-- **Install Script and `apm update`**: Repaired corrupted header in install.sh. Use awk instead of sed for shell subprocess compatibility. Directed shell output to terminal for password input during update process. 
+- **Install Script and `apm update`**: Repaired corrupted header in install.sh. Use awk instead of sed for shell subprocess compatibility. Directed shell output to terminal for password input during update process.
 
 ## [0.7.1] - 2025-01-22
 
@@ -496,7 +498,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **SKILL.md as first-class primitive**: meta-description of what an APM Package does for agents to read
 - **Claude Skills Installation**: Install Claude Skills directly as APM Packages
-- **Bidirectional Format Support**: 
+- **Bidirectional Format Support**:
   - APM packages → SKILL.md (for Claude target)
   - Claude Skills → .agent.md (for VSCode target)
 - **Skills Documentation**: New `docs/skills.md` guide
@@ -513,7 +515,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **Target Auto-Detection**: Smart compilation based on project structure
   - `.github/` only → generates `AGENTS.md` + VSCode integration
-  - `.claude/` only → generates `CLAUDE.md` + Claude integration  
+  - `.claude/` only → generates `CLAUDE.md` + Claude integration
   - Both folders → generates all formats
   - Neither folder → generates `AGENTS.md` only (universal format)
 

docs/src/content/docs/getting-started/authentication.md

@@ -281,3 +281,9 @@ git config credential.helper              # check current helper
 git config --global credential.helper osxkeychain  # macOS
 gh auth login                              # GitHub CLI
 ```
+
+### SSH connection hangs on corporate/VPN networks
+
+When no token is available, APM tries SSH before falling back to plain HTTPS. Firewalls that silently drop SSH packets (port 22) can make `apm install` appear to hang. APM sets `GIT_SSH_COMMAND="ssh -o ConnectTimeout=30"` so SSH attempts fail within 30 seconds and the fallback proceeds to HTTPS with git credential helpers.
+
+If you already set `GIT_SSH_COMMAND` (e.g., for a custom key), APM appends `-o ConnectTimeout=30` unless `ConnectTimeout` is already present in your value.

packages/apm-guide/.apm/skills/apm-usage/authentication.md

@@ -96,3 +96,15 @@ apm install --verbose your-org/package
 # Increase git credential timeout (default 30s, max 180s)
 export APM_GIT_CREDENTIAL_TIMEOUT=120
 ```
+
+### SSH connection hangs on corporate/VPN networks
+
+APM tries SSH as a fallback when HTTPS auth is not available. On networks
+that silently drop SSH traffic (port 22), this can appear to hang. APM sets
+`GIT_SSH_COMMAND="ssh -o ConnectTimeout=30"` so SSH attempts fail within
+30 seconds and the fallback chain continues to plain HTTPS with git
+credential helpers.
+
+To override the SSH command (e.g., custom key path), set `GIT_SSH_COMMAND`
+in your environment. APM appends `-o ConnectTimeout=30` unless it finds
+`ConnectTimeout` already present in your value.