Skip to main content

Using the npm auth token securely

Overview​

The Mobiscroll CLI saves your access token for the Mobiscroll NPM registry in the project's .npmrc file (and in .yarnrc.yml with Yarn 2 and newer). The token works like a password — anyone who has it can install the Mobiscroll packages with your account. Don't commit it to your repository and don't copy it into build images.

Keep the token in an environment variable named MOBISCROLL_NPM_TOKEN instead, and commit a configuration file that only references the variable:

.npmrc
@mobiscroll:registry=https://npm.mobiscroll.com
//npm.mobiscroll.com/:_authToken=${MOBISCROLL_NPM_TOKEN}

npm replaces ${MOBISCROLL_NPM_TOKEN} with the value of the environment variable when it runs. Set the variable on every machine and in every CI/CD service that installs the packages.

Get a token for automation​

Use a team NPM account for CI/CD instead of a developer's own account. A token created with a developer's account stops working when that developer changes their password, or when their license is assigned to someone else.

  1. Set up NPM access for your team on the licenses page.
  2. In the project root, log in with the team account's user name and secret:
mobiscroll login
  1. Open the .npmrc file in the project root and copy the value after //npm.mobiscroll.com/:_authToken=. Before you commit the file, replace the value with the ${MOBISCROLL_NPM_TOKEN} reference, as shown in the next section.
  2. Store the value as a secret named MOBISCROLL_NPM_TOKEN in your CI/CD service, as described in the sections below.

Reference the token in your configuration​

npm reads the registry settings from the .npmrc file in the project root. Commit this file:

.npmrc
@mobiscroll:registry=https://npm.mobiscroll.com
//npm.mobiscroll.com/:_authToken=${MOBISCROLL_NPM_TOKEN}

If the variable isn't set, npm leaves the ${MOBISCROLL_NPM_TOKEN} text as it is, and the registry rejects the request.

Local development​

Set MOBISCROLL_NPM_TOKEN in your user environment, so installs work in every terminal:

macOS / Linux
export MOBISCROLL_NPM_TOKEN="YOUR_MOBISCROLL_NPM_TOKEN"

This sets the variable for the current terminal session. To set it permanently, add the line to your ~/.bash_profile or ~/.zshrc file.

Windows
setx MOBISCROLL_NPM_TOKEN "YOUR_MOBISCROLL_NPM_TOKEN"

The setx command sets the variable permanently. It's available in new terminal windows, not in the current one.

The CLI writes the token into the project file

mobiscroll login, and mobiscroll config when you are not logged in, save the token itself to the project .npmrc file, and replace the ${MOBISCROLL_NPM_TOKEN} reference. With Yarn 2 and newer, the CLI also writes the token to the npmAuthToken value in .yarnrc.yml. Check these files before you commit them.

Move an existing project off a committed token​

  1. Replace the token in the committed .npmrc (or the npmAuthToken value in .yarnrc.yml) with the ${MOBISCROLL_NPM_TOKEN} reference shown above.
  2. Set MOBISCROLL_NPM_TOKEN on the development machines and in your CI/CD services.
  3. Replace the old token, because it stays in the history of your repository:
    • With a team NPM account, generate a new secret on the licenses page (Change access → Generate secret → Save). Projects that use the old token lose access. Get the new token as described in Get a token for automation, and update the stored MOBISCROLL_NPM_TOKEN values.
    • With a developer's own account, changing the password has the same effect.

CI/CD services​

GitHub Actions​

Add the token as a repository secret: Settings → Secrets and variables → Actions → Secrets tab → New repository secret. Name it MOBISCROLL_NPM_TOKEN. Organization and environment secrets work too.

Pass the secret to the install step as an environment variable. With npm, Yarn or Bun, the committed configuration file does the rest:

.github/workflows/build.yml
name: Build

on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
      - run: npm ci
        env:
          MOBISCROLL_NPM_TOKEN: ${{ secrets.MOBISCROLL_NPM_TOKEN }}
      - run: npm run build

With Yarn 1, set the variable for the whole job (env under the job instead of the step), because Yarn reads the configuration for every command. With Yarn 2 and newer, you can use the ${MOBISCROLL_NPM_TOKEN-} form instead.

With pnpm, let actions/setup-node create the user-level configuration. It writes the auth line to a .npmrc file on the runner, outside the repository, and reads the token from NODE_AUTH_TOKEN. Make sure pnpm is available on the runner before the install step:

.github/workflows/build.yml
      - uses: actions/setup-node@v7
        with:
          node-version: 24
          registry-url: https://npm.mobiscroll.com
          scope: '@mobiscroll'
      - run: pnpm install
        env:
          NODE_AUTH_TOKEN: ${{ secrets.MOBISCROLL_NPM_TOKEN }}
info

GitHub doesn't pass secrets to workflows triggered from forked repositories, so the install step fails in pull requests from forks.

GitLab CI/CD​

Add the token as a CI/CD variable: Settings → CI/CD → Variables → Add variable.

  • Key: MOBISCROLL_NPM_TOKEN
  • Visibility: Masked and hidden (or Masked), so the value doesn't show in job logs
  • Protect variable: optional — when selected, the variable is only available in pipelines that run on protected branches or tags

GitLab sets CI/CD variables as environment variables in the job, so the committed configuration file works without extra steps:

.gitlab-ci.yml
default:
  image: node:24

build:
  stage: build
  script:
    - npm ci
    - npm run build

Azure Pipelines​

Add the token as a secret variable: open the pipeline, select Edit → Variables, add MOBISCROLL_NPM_TOKEN, select Keep this value secret, then save the pipeline. To share the token between pipelines, use a variable group.

Azure Pipelines doesn't pass secret variables to scripts automatically. Map the variable on the install step:

azure-pipelines.yml
pool:
  vmImage: ubuntu-latest

steps:
  - task: UseNode@1
    inputs:
      version: '24.x'
  - script: npm ci
    displayName: Install dependencies
    env:
      MOBISCROLL_NPM_TOKEN: $(MOBISCROLL_NPM_TOKEN)
  - script: npm run build
    displayName: Build

Azure Pipelines also has an npm Authenticate task that adds credentials from an npm service connection to the .npmrc file for the duration of the build.

Docker​

Use a build secret. BuildKit makes it available only to the RUN instruction that mounts it, and doesn't store it in the image or the build cache:

Dockerfile
# syntax=docker/dockerfile:1
FROM node:24-slim AS build
WORKDIR /app
COPY package.json package-lock.json .npmrc ./
RUN --mount=type=secret,id=MOBISCROLL_NPM_TOKEN,env=MOBISCROLL_NPM_TOKEN,required=true \
    npm ci
COPY . .
RUN npm run build

FROM node:24-slim
WORKDIR /app
# Copy only what the app needs at runtime, for example the build output
COPY --from=build /app/dist ./dist
# ...
  • env=MOBISCROLL_NPM_TOKEN exposes the secret as an environment variable, so the committed .npmrc works as it is. It requires Dockerfile syntax 1.10 or newer, which the # syntax=docker/dockerfile:1 line selects.
  • required=true stops the build with an error when the secret isn't provided.
  • With a multi-stage build, files from the build stage, like node_modules, only end up in the final image if you copy them with COPY --from.
  • With Yarn, every RUN instruction that runs Yarn reads the configuration. Mount the secret on each of them, or use the ${MOBISCROLL_NPM_TOKEN-} form with Yarn 2 and newer.

Pass the variable from your shell or CI/CD service when you build the image:

docker build --secret id=MOBISCROLL_NPM_TOKEN,env=MOBISCROLL_NPM_TOKEN -t my-app .

Add a .dockerignore file to keep local files in the project root, like .env files and node_modules, out of the build context:

.dockerignore
node_modules
.env*
Don't pass the token with ARG or ENV

Build arguments and environment variables persist in the final image, and build arguments are visible in the docker history output. Don't copy an .npmrc file that contains the token value into the image either — the committed .npmrc above only contains the reference.

With pnpm, copy pnpm-lock.yaml instead of package-lock.json, make sure pnpm is installed in the image, and write the token reference to the user-level configuration in the same RUN instruction. The image stores the reference, not the token:

Dockerfile
RUN --mount=type=secret,id=MOBISCROLL_NPM_TOKEN,env=MOBISCROLL_NPM_TOKEN,required=true \
    pnpm config set '//npm.mobiscroll.com/:_authToken' '${MOBISCROLL_NPM_TOKEN}' && \
    pnpm install

Docker Compose​

Declare the secret for the service build, and take its value from the MOBISCROLL_NPM_TOKEN environment variable. The secret ID matches the one in the Dockerfile above:

compose.yaml
services:
  app:
    build:
      context: .
      secrets:
        - MOBISCROLL_NPM_TOKEN

secrets:
  MOBISCROLL_NPM_TOKEN:
    environment: MOBISCROLL_NPM_TOKEN

Then build with docker compose build.

Hosting platforms​

The steps below apply to projects that install with npm, Yarn or Bun and use the committed configuration file from above. Vercel and Netlify make project environment variables available during the build, so the package manager can read MOBISCROLL_NPM_TOKEN when it installs the packages.

Vercel​

  1. Open your project and select Settings → Environment Variables.
  2. Add MOBISCROLL_NPM_TOKEN with the token as the value, and select the environments that build your project (Production, Preview).
  3. Choose Secret (not Config), so the value can't be viewed after you save it.
  4. Save the variable and redeploy. Changes to environment variables only apply to new deployments.

Netlify​

  1. Open your project and select Project configuration → Environment variables → Add a variable → Add a single variable.
  2. Enter MOBISCROLL_NPM_TOKEN as the key and the token as the value.
  3. Select Contains secret values. If you limit the scopes of the variable, include Builds.
  4. Create the variable, then start a new build and deploy.
info

With Contains secret values selected, Netlify's secrets scanning fails the build if the token value appears in the repository code or the build output. Don't set the token in netlify.toml — that file is stored in your repository.

Troubleshooting​

When the token is missing, the install stops with an error like one of these:

Package managerError
npmnpm error code E403 and unregistered users are not allowed to access package
pnpmERR_PNPM_FETCH_403 and No authorization header was set for the request.
Yarn 1Failed to replace env in config: ${MOBISCROLL_NPM_TOKEN}
Yarn 2+Environment variable not found (MOBISCROLL_NPM_TOKEN)
Bunerror: GET https://npm.mobiscroll.com/@mobiscroll%2freact - 403

The exact wording depends on the package manager version. Check the following:

  • The variable is set in the environment that runs the package manager — in GitHub Actions in the env of the step (or the job), in Azure Pipelines mapped with env on each step that needs it. With Yarn, every step that runs Yarn needs it.
  • The variable is available in the current pipeline: protected GitLab variables are only available on protected branches and tags, and GitHub doesn't pass secrets to workflows from forked repositories.
  • With pnpm, the output doesn't contain an Ignored project-level auth setting warning. If it does, move the token reference to the user-level configuration, as described in the pnpm tab above.
  • On Vercel and Netlify, you started a new deployment after adding the variable.

Security checklist​

  • Keep the token only in environment variables and the secret stores of your CI/CD services — never in committed files, Dockerfiles, netlify.toml or build images.
  • Pass the token only to the steps that need it: the install step with npm, pnpm and Bun. Yarn reads the token for every command — with Yarn 2 and newer, the ${MOBISCROLL_NPM_TOKEN-} form keeps the other steps working without it.
  • Don't print the token. Log masking in CI/CD services is a best-effort protection, not a guarantee.
  • Use a team NPM account instead of a developer's own credentials.
  • If the token leaks, generate a new team secret and update the stored values. If a job log contains the token, delete the log as well.