Add a new app to Provenix¶
In this tutorial, you'll put an existing JavaScript app behind Provenix. By the end:
- the app's CI pipelines and developer machines install every package through Provenix, each with its own token,
- the dependencies the app already uses are approved, so the switch doesn't break a single build,
- you'll have seen the two things Provenix does every day: block a package nobody has approved, and hold a new version while your builds keep using the previous one.
The examples use an app called shop-web, built by the shop team,
with two GitHub Actions jobs: build on every pull request and release on
main. Swap in your own names as you go.
Before you start¶
You'll need:
- The admin role in your Provenix workspace, or someone who has it to work through steps 2 to 4 with you.
-
The Provenix URLs for your organisation. These docs use:
Example Registry (what npm talks to) https://npm.example.com/Console https://provenix.example.com -
The app's repository, with a committed lockfile:
package-lock.json,yarn.lockorpnpm-lock.yaml. - Permission to add CI secrets to that repository.
curlandjqfor the optional API steps.
Allow about 30 minutes, plus however long seeding takes for your lockfile.
1. Plan your clients¶
Provenix identifies an npm client only by its token. Every install, review request and lockfile submission is attributed to the client that owns the token. So give each thing you want to tell apart its own client:
- one client per CI pipeline, for example
ci-shop-web-buildandci-shop-web-release, - one client per developer machine, for example
laptop-jsmith, - optionally, a group per team (
shop-team) to roll them up.
Don't share one token across pipelines
It's tempting to create one client for the whole app, or the whole company. Don't:
- Attribution merges. When a bad version turns up, "which pipelines installed it?" can only be answered with the shared client.
- Rotation is all-or-nothing. If the token leaks from one pipeline's logs, you have to replace it in every pipeline at once, and until you do, it can install anything the workspace allows.
- Lockfile submissions overwrite each other. Each client keeps one lockfile snapshot, so two repositories on one client keep only whichever submitted last.
For shop-web, write down three clients: ci-shop-web-build,
ci-shop-web-release, and one per developer.
2. Create a group for the team (optional)¶
Groups let reviewers see installs by team. Skip this step if you don't need them: clients work the same without a group.
Note
The console shows a client's group but can't create groups yet, so this
step uses the admin API. You need an admin API key for your workspace
(it starts with dfsa_); ask whoever runs Provenix for one with the
write scope.
export PROVENIX_URL=https://provenix.example.com
export PROVENIX_ADMIN_KEY='dfsa_…'
GROUP_ID=$(curl -sSf -X POST "$PROVENIX_URL/api/v1/client-groups" \
-H "Authorization: Bearer $PROVENIX_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "shop-team"}' | jq -r .id)
echo "$GROUP_ID"
These paths are for your organisation's default workspace. For another
workspace, start the path with /api/v1/workspaces/<workspace id> instead of
/api/v1.
3. Register the clients¶
Each client gets a token that starts with df_live_. The token is shown
once, so have the place you'll store it (your CI secrets page, or the
developer it's for) ready before you create it.
- Open Clients.
- Under Register a client, enter
ci-shop-web-buildand select Create. - Copy the token from Client token — shown once, copy it now and store it (see step 6).
- Repeat for
ci-shop-web-releaseand each developer machine.
Clients you create in the console have no group. To put one in the group from step 2, use the API.
curl -sSf -X POST "$PROVENIX_URL/api/v1/clients" \
-H "Authorization: Bearer $PROVENIX_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "ci-shop-web-build", "group_id": "'"$GROUP_ID"'"}' \
| jq -r .token
Store the printed token straight away, then repeat for the other clients. To move a client you created in the console into the group:
curl -sSf -X PATCH "$PROVENIX_URL/api/v1/clients/<client id>" \
-H "Authorization: Bearer $PROVENIX_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"group_id": "'"$GROUP_ID"'"}'
4. Seed the app's current dependencies¶
If you pointed shop-web at Provenix now, every package Provenix hasn't seen
would fail with a 451 and wait in discovery, and a lockfile of a few
hundred packages would take hours. Seeding imports the whole lockfile in
one go instead.
With Trust baseline on, the exact versions in the lockfile are approved straight away: you're telling Provenix "these are what we already run". Versions published after the seed still go through scanning and quarantine.
- In the console, open Seed.
- Paste the contents of the app's lockfile into Lockfile contents.
- Leave Lockfile format on
auto, or picknpm,yarnorpnpm. - Make sure Trust baseline is ticked.
- Select Start seed.
- Wait until the job's status is
completed. A few hundred packages usually take a few minutes. If it endsfailed, open the job to see which packages didn't import.
Seeding from the command line
The same job through the API, for very large lockfiles or scripts:
jq -n --rawfile lock package-lock.json \
'{lockfile: $lock, lockfile_format: "auto", trust_baseline: true}' |
curl -sSf -X POST "$PROVENIX_URL/api/v1/seed" \
-H "Authorization: Bearer $PROVENIX_ADMIN_KEY" \
-H "Content-Type: application/json" \
--data-binary @-
Then poll GET /api/v1/seed/<id> until status is completed.
Seeding doesn't use up the per-client discovery limits, and every version it approves is recorded in the audit log.
5. Point the app at Provenix¶
Add the registry settings to the repository. The token itself never goes in
the file: it's read from the PROVENIX_NPM_TOKEN environment variable, so
the file can be committed and each pipeline or developer supplies their
own.
.npmrc in the repository root:
registry=https://npm.example.com/
//npm.example.com/:_authToken=${PROVENIX_NPM_TOKEN}
always-auth=true
replace-registry-host=never
.yarnrc.yml in the repository root:
npmRegistryServer: "https://npm.example.com"
npmRegistries:
"https://npm.example.com":
npmAuthToken: "${PROVENIX_NPM_TOKEN}"
npmAlwaysAuth: true
nodeLinker: node-modules
Yarn Berry's Plug'n'Play mode isn't covered by Provenix's client tests
yet, so use nodeLinker: node-modules.
Point the lockfile at Provenix too¶
Your lockfile still records where each package was downloaded from, for
example https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz. npm and
Yarn classic can use those URLs directly, which would skip Provenix
entirely for every package already in the lockfile. Rewrite them once so
every download goes through Provenix:
perl -pi -e 's#https://registry\.(npmjs\.org|yarnpkg\.com)/#https://npm.example.com/#g' package-lock.json
grep -cE 'registry\.(npmjs\.org|yarnpkg\.com)' package-lock.json
perl -pi -e 's#https://registry\.(npmjs\.org|yarnpkg\.com)/#https://npm.example.com/#g' yarn.lock
grep -cE 'registry\.(npmjs\.org|yarnpkg\.com)' yarn.lock
Nothing to do. These lockfiles don't record download URLs for registry packages, so they always download from the configured registry.
The grep prints 0 when no upstream URL is left. Provenix serves tarballs
at the same paths as npm, so only the host changes and integrity hashes stay
valid.
Commit .npmrc (or .yarnrc.yml) and the lockfile together.
6. Add the tokens to CI¶
Store each pipeline's token as a secret on that pipeline only, then expose
it to the install step as PROVENIX_NPM_TOKEN.
- In the repository, open Settings → Secrets and variables →
Actions and add
PROVENIX_NPM_TOKEN_BUILD(theci-shop-web-buildtoken) andPROVENIX_NPM_TOKEN_RELEASE. - Pass the right one to each job:
jobs:
build:
runs-on: ubuntu-latest
env:
PROVENIX_NPM_TOKEN: ${{ secrets.PROVENIX_NPM_TOKEN_BUILD }}
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm whoami
- run: npm ci
- run: npm test
Don't set registry-url on actions/setup-node: it writes its own
.npmrc that expects a different variable, and you want the
repository's.
- Under Settings → CI/CD → Variables, add
PROVENIX_NPM_TOKENas a masked variable. To give each job its own client, add one variable per job and map it in the job'svariables:. - The install step needs nothing else:
build:
image: node:22
script:
- npm whoami
- npm ci
- npm test
npm whoami prints the name of the client that owns the token, for example
ci-shop-web-build. If it prints something else, the pipeline has the wrong
secret.
Developers do the same on their own machines, with their own client's token in their shell profile:
export PROVENIX_NPM_TOKEN='df_live_…'
7. Run a clean install¶
Prove that the app installs entirely from Provenix, with nothing coming from a local cache:
rm -rf node_modules
npm ci --cache "$(mktemp -d)"
You should see no 451 errors: everything in the lockfile was approved by
the seed. Then push the branch and check that the CI jobs pass the same
way.
If something does fail with a 451, it wasn't in the lockfile you seeded
(for example, a package added since). See
When an install is blocked.
8. Submit the lockfile from CI¶
Provenix sees which versions your app installs, but not the ranges in your
package.json (^4.17.0). Submitting the lockfile tells it, so it can show
which clients would pick up a new version and enforce policies such as
requiring pinned versions.
Add a step to the job that runs on main, after the install:
- name: Submit lockfile to Provenix
run: |
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 @-
The step uses the job's own client token, and me stands for its client.
The response counts what was stored:
{ "format": "npm", "ranges": 1184, "direct": 42, "skipped": 2, "unpinned_direct": 37 }
unpinned_direct is how many of your direct dependencies use a range
rather than an exact version. For pnpm, Yarn classic and older lockfiles,
see Submit your lockfile from CI.
9. Try it: add a package Provenix hasn't seen¶
Your app is set up. Now see what your developers will see. On a branch, add a package nobody in your workspace has used yet:
npm install left-pad
The install fails with a 451:
npm error code E451
npm error 451 Unavailable For Legal Reasons - GET https://npm.example.com/left-pad - package_not_approved
npm prints only the error code. To read Provenix's full answer, ask for the package directly:
curl -sS -H "Authorization: Bearer $PROVENIX_NPM_TOKEN" \
https://npm.example.com/left-pad | jq
{
"error": "package_not_approved",
"message": "Provenix has not approved \"left-pad\" yet; discovery has been queued. Estimated availability: 2026-11-29T10:00:00Z. Status: https://provenix.example.com/packages/left-pad",
"package": "left-pad",
"estimated_available_at": "2026-11-29T10:00:00Z",
"console_url": "https://provenix.example.com/packages/left-pad"
}
Provenix is now fetching and scanning left-pad. A brand-new package is
held for longer than a new version of one you already use: 7 days by
default.
If your team needs it sooner, ask for a review of the exact version you want:
curl -sSf -X POST \
"https://provenix.example.com/api/v1/packages/left-pad/versions/1.3.0/request-review" \
-H "Authorization: Bearer $PROVENIX_NPM_TOKEN" \
-H "Content-Type: application/json" \
-d '{"justification": "Needed for the shop-web checkout page"}'
In the console, the version now shows an Expedited badge in
Quarantine. A reviewer opens it, reads the findings, and selects
Approve (or Reject). Once it's approved, run the same
npm install left-pad again. It works with no change on your side.
10. Try it: a new version is published upstream¶
The other thing Provenix does is hold new versions of packages you already use. When a dependency publishes a new version upstream:
- Provenix notices it and starts scanning it. It appears in Quarantine in the console.
- Your installs carry on as before. A range like
^4.17.0resolves to the newest approved version, and the response says which one it served in theX-DF-Served-Versionheader. - When the hold ends (by default 24 hours after Provenix first saw it, and at least 72 hours after it was published), a version that scored well is approved automatically. Anything else waits for a reviewer.
You don't need to do anything for this: it's what stops a compromised release from reaching your builds on the day it's published.
What you've done¶
- Registered one client per pipeline and per developer, so every install is attributed to where it came from.
- Seeded the app's existing dependencies as a trusted baseline.
- Pointed the app, its lockfile and its CI at Provenix.
- Submitted the lockfile so Provenix knows your declared ranges.
- Seen an unknown package blocked, reviewed and approved.
Next steps¶
- When an install is blocked: what each
451means and what to do. - Request an expedited review.
- Rotate a client token if one leaks.
- Configure npm, Yarn and pnpm for the details of each client.