Submit your lockfile from CI¶
Install traffic tells Provenix which versions you use, but not the ranges
your package.json declares (^4.17.0). Submitting your lockfile tells it.
With your ranges, Provenix can:
- show which clients would pick up a new version as soon as it's approved,
- apply policies that need ranges, such as requiring exact versions for direct dependencies.
A client that never submits a lockfile still installs normally. Those features just don't apply to it.
When to submit¶
Each submission replaces the client's previous one. Submit after every change to the lockfile: the simplest way is a step in the CI job that runs on your main branch, after the install.
Use one client per repository. Two repositories submitting with the same token overwrite each other.
Submit it¶
The request goes to the registry host, with the client token the job
already uses. me stands for the token's own client.
jq -n --rawfile lock package-lock.json '{lockfile: $lock}' |
curl -sSf -X POST "https://npm.example.com/api/v1/clients/me/lockfile" \
-H "Authorization: Bearer $PROVENIX_NPM_TOKEN" \
-H "Content-Type: application/json" \
--data-binary @-
jq -n --rawfile lock pnpm-lock.yaml '{lockfile: $lock}' |
curl -sSf -X POST "https://npm.example.com/api/v1/clients/me/lockfile" \
-H "Authorization: Bearer $PROVENIX_NPM_TOKEN" \
-H "Content-Type: application/json" \
--data-binary @-
pnpm lockfiles record only your direct dependencies' ranges, so that's all Provenix stores.
jq -n --rawfile lock yarn.lock '{lockfile: $lock}' |
curl -sSf -X POST "https://npm.example.com/api/v1/clients/me/lockfile" \
-H "Authorization: Bearer $PROVENIX_NPM_TOKEN" \
-H "Content-Type: application/json" \
--data-binary @-
These lockfiles don't record which dependencies are direct, so send
package.json too:
jq -n --rawfile lock yarn.lock --rawfile pkg package.json \
'{lockfile: $lock, package_json: $pkg}' |
curl -sSf -X POST "https://npm.example.com/api/v1/clients/me/lockfile" \
-H "Authorization: Bearer $PROVENIX_NPM_TOKEN" \
-H "Content-Type: application/json" \
--data-binary @-
For an npm v1 lockfile, use package-lock.json in place of
yarn.lock.
The response¶
{
"format": "npm",
"ranges": 1184,
"direct": 42,
"skipped": 2,
"unpinned_direct": 37,
"submitted_at": "2026-11-22T09:15:00Z"
}
| Field | Meaning |
|---|---|
ranges |
Dependency ranges stored, direct and transitive |
direct |
How many of them are your own direct dependencies |
skipped |
Entries Provenix doesn't track: git, file:, link: and workspace: dependencies, and tarball URLs |
unpinned_direct |
Direct dependencies that use a range rather than an exact version |
If it fails¶
| Status | Meaning |
|---|---|
400 invalid_lockfile |
The lockfile couldn't be read. The message says why; for Yarn classic or npm v1, it's often a missing package_json. |
401 |
The token isn't valid. |
413 |
The request is over 32 MiB. |
Your workspace admin can see the stored snapshot for each client in the console under Clients.