Private package names: prevent a public registry winning resolution

Last updated: 5 Oct 20266 min read

tutorial

A build that searches public and private package indexes may select a public package with the same name as an internal dependency. Some package managers do not prioritize the private index simply because it is listed first. A higher matching version can be chosen from an unintended source, turning an ordinary dependency update into a supply-chain incident. A lockfile helps only if its package identity and source are checked and enforced by the installer.

Operational decision

A receipt processor depends on an internal payment-rule library. Put internal packages in an organization-controlled namespace where the ecosystem supports it, and configure the installer so that the internal name resolves only through the approved repository. The text contract avoids assuming one package manager's syntax is portable to another. In a disposable registry test, publish a higher-version collision under a look-alike public name and confirm the build refuses it. Generate a resolution report from a clean runner and inspect package name, source registry, version, and checksum before release. If a mirror is used, verify it authenticates upstream sources and cannot silently substitute a different artifact for the same lock entry. Do not repair a failed private-registry lookup by enabling every public fallback during an incident; that changes the trust boundary at the moment controls are weakest. Keep package publish rights separate from package read rights.

Receipt dependency resolution contract
Internal namespace: organization-owned payment packages
Source: approved private registry or authenticated mirror only
Lock record: exact package, source, version, checksum
Clean-runner check: reject public collision and source mismatch
Publish permission: separate from build read permission

Cost and verification

An isolated private feed and authenticated mirror add hosting, credential, and availability costs. Public fallback can improve availability but may admit an unintended package; decide the source policy before an outage. Check the dependency graph from a clean runner because a warm cache can hide a wrong registry configuration. Monitor package-source changes and new publisher identities as release signals. An exact version alone is not enough when two registries can serve different bytes under the same name.

Common Mistakes

Do not assume a listed private index has priority over every public candidate.
Do not accept a dependency solely because its version matches the lock entry.
Do not give routine build jobs package-publish authority.

Connected lessons

Practice and check

Supply evidence follow-up

Package identity: verify advisory matches before changing a release

devops

operations