Add JFrog Artifactory VCS repository support

[chkp-roniz]

Motivation

Enterprise environments often cannot allow direct outbound git connections to GitHub, GitLab, or other public Git hosts. JFrog Artifactory is widely deployed as a caching proxy that sits between internal networks and external repositories, providing:

• Network isolation — all traffic routes through a single, auditable gateway
• Artifact caching — repeated installs don't hit the public internet
• Access control — centralized auth and audit logging
• Air-gapped support — fully disconnected environments with pre-populated caches

APM currently requires git clone for all package downloads, which fails behind Artifactory because Artifactory VCS Remote Repositories serve zip archives over HTTP, not the git protocol. This PR adds Artifactory as a first-class package source alongside GitHub, GitLab, Bitbucket, and Azure DevOps.

What changed

Three operating modes

Mode	How to use	What happens
Mode 1: Explicit FQDN	apm install art.company.com/artifactory/github/owner/repo	Downloads zip archive directly from specified Artifactory instance
Mode 2: Transparent proxy	Set ARTIFACTORY_BASE_URL	All GitHub-hosted packages automatically route through Artifactory
Air-gapped mode	Set ARTIFACTORY_ONLY=1 + ARTIFACTORY_BASE_URL	Blocks all direct git clones; everything goes through Artifactory

Key implementation details

• Zip archive download with root-prefix stripping (GitHub/GitLab archives contain a {repo}-{ref}/ root directory)
• Multi-format URL support — tries both GitHub-style (/archive/refs/heads/{ref}.zip) and GitLab-style (/-/archive/{ref}/{repo}-{ref}.zip) patterns, so the same code works regardless of what upstream VCS sits behind Artifactory
• ARTIFACTORY_APM_TOKEN env var for authenticated access (Bearer token)
• Install paths are source-agnostic — apm_modules/owner/repo/ whether installed from GitHub or Artifactory, enabling seamless source switching
• Lockfile compatibility — resolved_commit is None for Artifactory packages (no git SHA available); lockfile still tracks branch/tag reference
• Virtual/subdirectory packages — file downloads and subdirectory extraction both route through Artifactory when configured

Security

• Zip path traversal protection (CWE-22) — entries with ../ are silently skipped
• Configurable archive size limit via ARTIFACTORY_MAX_ARCHIVE_MB (default 500 MB)
• URL scheme validation — only https:// and http:// accepted for ARTIFACTORY_BASE_URL

Files changed

File	Change
src/apm_cli/utils/github_host.py	+3 functions: is_artifactory_path, parse_artifactory_path, build_artifactory_archive_url
src/apm_cli/models/dependency.py	artifactory_prefix field, is_artifactory() method, parsing/serialization
src/apm_cli/deps/github_downloader.py	Artifactory download methods, proxy routing, ARTIFACTORY_ONLY mode
src/apm_cli/commands/install.py	Preserve Artifactory prefix in transitive download callback
src/apm_cli/core/token_manager.py	artifactory_modules token precedence
docs/.../authentication.md	Artifactory row in token table
CHANGELOG.md	Unreleased entry
tests/unit/test_artifactory_support.py	61 new tests

Type of change

• New feature

Testing

• Tested locally
• All existing tests pass (175 passed, 2 skipped, 0 new failures)
• Added tests for new functionality (61 tests covering path detection, URL building, parsing, download/extraction, token management, proxy routing, edge cases, and ARTIFACTORY_ONLY mode)
• End-to-end verified with real Artifactory instance proxying both GitHub and GitLab upstreams

[Copilot]

Pull request overview

This PR adds first-class support for installing APM packages through JFrog Artifactory VCS repositories, including explicit Artifactory dependency syntax, a transparent proxy mode via ARTIFACTORY_BASE_URL, and an air-gapped mode (ARTIFACTORY_ONLY) that blocks direct git operations.

Changes:

• Add Artifactory path parsing and archive URL construction helpers.
• Route downloads through Artifactory (archive-based install + file/subdir extraction) with new token purpose ARTIFACTORY_APM_TOKEN.
• Add unit tests plus updates to authentication docs and the changelog.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
tests/unit/test_artifactory_support.py	Adds comprehensive tests for Artifactory parsing, proxy routing, archive/file extraction, and air-gapped behavior.
src/apm_cli/utils/github_host.py	Introduces Artifactory path detection/parsing and archive URL builders.
src/apm_cli/models/dependency.py	Extends dependency parsing/canonicalization and URL generation to include Artifactory references.
src/apm_cli/deps/github_downloader.py	Implements Artifactory archive download/extraction and proxy/air-gapped routing logic.
src/apm_cli/core/token_manager.py	Adds artifactory_modules token purpose and env var mapping.
src/apm_cli/commands/install.py	Ensures repo refs built for install include Artifactory prefix when applicable.
docs/src/content/docs/getting-started/authentication.md	Documents the new Artifactory auth token environment variable.
CHANGELOG.md	Adds an Unreleased entry describing Artifactory support.

---

You can also share your feedback on Copilot code review. Take the survey.

[chkp-roniz]

@microsoft-github-policy-service agree company="Check Point"