Skip to content

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.lock or pnpm-lock.yaml.

  • Permission to add CI secrets to that repository.
  • curl and jq for 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-build and ci-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.

  1. Open Clients.
  2. Under Register a client, enter ci-shop-web-build and select Create.
  3. Copy the token from Client token — shown once, copy it now and store it (see step 6).
  4. Repeat for ci-shop-web-release and 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.

  1. In the console, open Seed.
  2. Paste the contents of the app's lockfile into Lockfile contents.
  3. Leave Lockfile format on auto, or pick npm, yarn or pnpm.
  4. Make sure Trust baseline is ticked.
  5. Select Start seed.
  6. Wait until the job's status is completed. A few hundred packages usually take a few minutes. If it ends failed, 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.

  1. In the repository, open Settings → Secrets and variables → Actions and add PROVENIX_NPM_TOKEN_BUILD (the ci-shop-web-build token) and PROVENIX_NPM_TOKEN_RELEASE.
  2. 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.

  1. Under Settings → CI/CD → Variables, add PROVENIX_NPM_TOKEN as a masked variable. To give each job its own client, add one variable per job and map it in the job's variables:.
  2. 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:

  1. Provenix notices it and starts scanning it. It appears in Quarantine in the console.
  2. Your installs carry on as before. A range like ^4.17.0 resolves to the newest approved version, and the response says which one it served in the X-DF-Served-Version header.
  3. 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