Skip to content

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.