Skip to content

[docs] Update documentation for Artifactory archive entry download (2026-04-05) #579

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

Closed
danielmeppiel wants to merge 1 commit into from
+16 −0
Closed

[docs] Update documentation for Artifactory archive entry download (2026-04-05) #579

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
4 changes: 4 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Unified integration dispatch table in `dispatch.py` -- both install and uninstall import from one source of truth (#562)
- Hook merge logic deduplicated: three copy-pasted JSON-merge methods replaced with `_integrate_merged_hooks()` + config dict (#562)

### Added

- Artifactory Archive Entry Download for virtual file packages: single-file primitives (`.prompt.md`, `.agent.md`, etc.) are now fetched via the `!/{path}` entry API instead of a full archive download, with transparent fallback on unsupported Artifactory versions (#525)

Comment on lines +17 to +20
Copy link

Copilot AI Apr 5, 2026

Choose a reason for hiding this comment

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

The [Unreleased] section now includes an entry for feature PR #525, but the changelog already documents #525 under the released 0.8.10 section (and with a different category: Changed). This will cause duplicate/misleading release notes. Consider removing this new Unreleased entry; if the intent is to track this documentation-only PR, add a concise entry that references this PR number instead of #525.

Suggested change
### Added
- Artifactory Archive Entry Download for virtual file packages: single-file primitives (`.prompt.md`, `.agent.md`, etc.) are now fetched via the `!/{path}` entry API instead of a full archive download, with transparent fallback on unsupported Artifactory versions (#525)

Copilot uses AI. Check for mistakes.
### Fixed

- `apm deps update -g` now correctly passes scope, preventing user-scope updates from silently using project-scope paths (#562)
Expand Down
12 changes: 12 additions & 0 deletions docs/src/content/docs/getting-started/authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -199,6 +199,18 @@ With `PROXY_REGISTRY_ONLY=1`, APM will:
2. Skip the download cache for entries that have no `registry_prefix` (forcing a fresh proxy download)
3. Raise an error for any package reference that does not route through the configured proxy

### Archive Entry Download (virtual file packages)

When downloading virtual file packages (`.prompt.md`, `.agent.md`, and similar single-file primitives) through an Artifactory proxy, APM uses the **Archive Entry Download API** to fetch only the specific file instead of the full archive.

The entry URL follows the Artifactory pattern:

```
GET {archive_url}!/{repo}-{ref}/{file_path}
```

This avoids downloading a multi-MB archive just to extract a single small file. If the entry API returns a 404, a connection error, or is unsupported by the Artifactory version in use, APM falls back to the standard full-archive download transparently -- no configuration required.

Comment on lines +202 to +213
Copy link

Copilot AI Apr 5, 2026

Choose a reason for hiding this comment

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

This new subsection documents the Artifactory archive-entry optimization in the public docs, but the corresponding apm-usage skill content likely also needs the same update so CLI/help guidance stays consistent (see packages/apm-guide/.apm/skills/apm-usage/authentication.md, which currently only mentions proxy env vars). Consider adding a matching brief subsection there as well.

Copilot uses AI. Check for mistakes.
### Deprecated Artifactory env vars

The following env vars still work but emit a `DeprecationWarning`. Migrate to the `PROXY_REGISTRY_*` equivalents:
Expand Down
Loading