Git SHA Installs

nproxy can proxy and cache packages installed by git commit SHA. Instead of relying on npm's default git resolution (which bypasses the registry proxy entirely), you specify dependencies as tarball URLs through your nproxy endpoint. nproxy fetches from GitHub's archive API, caches permanently, and serves the tarball.

Why pin to a git SHA

Exact commit = immutable. No branch drift, no tag mutation attacks. The SHA points to one commit forever.
All installs flow through nproxy. You get caching, audit trail, and visibility -- the same guarantees as registry packages.
No git clone needed. Faster installs, no git binary requirement in CI.
Standard tarball URL. Works with lockfiles, npm ci, and all package managers (npm, pnpm, yarn).

URL format

https://<org>.nproxy.app/-/git/<host>/<owner>/<repo>/<sha>.tgz

Segment	Example	Description
`<org>`	`acme`	Your nproxy org slug
`<host>`	`github.com`	Git hosting provider
`<owner>`	`facebook`	Repository owner
`<repo>`	`react`	Repository name
`<sha>`	`a1b2c3d4e5f6`	Full or short commit SHA

Usage

Add the tarball URL as a dependency in your package.json:

{
  "dependencies": {
    "my-lib": "https://acme.nproxy.app/-/git/github.com/org/my-lib/a1b2c3d4e5f6.tgz"
  }
}

npm resolves this as a tarball URL, fetches it through nproxy, and records the resolved URL plus integrity hash in the lockfile. npm ci works as expected -- subsequent installs use the lockfile entry and hit nproxy's cache.

Finding the commit SHA

# Latest commit on main
git ls-remote https://github.com/org/repo HEAD

# Specific tag
git ls-remote https://github.com/org/repo refs/tags/v1.0.0

# From a local clone
git rev-parse HEAD

Caching

Git SHAs are immutable -- a commit hash always points to the same content. nproxy caches git tarballs permanently with no TTL. The first install fetches from GitHub's codeload archive API. Subsequent installs serve from cache (R2 for the cloud proxy, filesystem for the local proxy).

Response headers indicate cache behavior:

Header	Values	Description
`x-nproxy-cache`	`hit`, `miss`	Whether the tarball was served from cache
`x-nproxy-source`	`git`	Indicates the package was fetched from a git archive

Current limitations

GitHub only. GitLab and Bitbucket support is planned.
Public repositories only. Private repo support requires GitHub auth and is coming soon.
No security rule analysis. Git tarballs are served as-is -- nproxy does not run security rules on them yet.
Root package.json required. The repository must have a package.json at the root (npm requirement for tarball installs).