Use this guide when you want to run CI or deploy your app. You will:

  • Create a token for each place that installs your app
  • Set up GitHub Actions or another CI provider
  • Set up your deployment, with or without Docker

The .npmrc you committed sends @adonisplus packages to the Plus registry, but it holds no token. On your computer, the token comes from your own npm config. CI runners and deployment builds do not have it, so each one needs a token of its own.

Create one token for each place, and name it after that place, like "GitHub Actions" or "Fly.io". When you revoke one, the others keep working.

Open Tokens on your dashboard, type a name, and select "Create token". Copy the token right away, because it is not shown again. If you lose it, revoke it and create a new one.

Save it in that place as a secret named ADONISJS_PLUS_TOKEN. The sections below show where.

Paste this prompt into your coding agent, in the root of your project. It finds your CI and deployment, adds the registry token to each, and asks before it commits anything.

Set up the AdonisJS Plus registry for CI and deployment in this project. If a step fails, work out what is wrong and fix it.

1. Find the package manager from the lockfile. Read the owner and repository from the GitHub remote, if there is one, and check whether `gh auth status` prints my account.

2. Find where the project installs its packages without me: the workflows in .github/workflows, other CI files (.gitlab-ci.yml, .circleci/config.yml, bitbucket-pipelines.yml and others), a Dockerfile, fly.toml, and railway.json or render.yaml. Tell me what you found, and ask me which ones to set up and whether I deploy anywhere else.

3. In each GitHub Actions workflow that installs packages, give actions/setup-node `registry-url: https://plus.adonisjs.com/registry/` and `scope: '@adonisplus'`, and pass `NODE_AUTH_TOKEN: ${{ secrets.ADONISJS_PLUS_TOKEN }}` to the install step. With Yarn, which does not read .npmrc, add a step before the install that runs `yarn config set --home npmScopes.adonisplus.npmAuthToken "$ADONISJS_PLUS_TOKEN"` with `ADONISJS_PLUS_TOKEN: ${{ secrets.ADONISJS_PLUS_TOKEN }}` in its env, in place of NODE_AUTH_TOKEN.

4. In other CI providers, and on platforms that build without Docker, run the install as one command that adds the token and removes the file after:
   printf '\n//plus.adonisjs.com/registry/:_authToken=%s\n' "$ADONISJS_PLUS_TOKEN" >> .npmrc && <install command> && rm -f .npmrc
   With Yarn, run `yarn config set --home npmScopes.adonisplus.npmAuthToken "$ADONISJS_PLUS_TOKEN"` before the install instead.

5. In a Dockerfile, change the install step to read the token from a BuildKit secret, as https://plus.adonisjs.com/docs/get-started/ci-and-deployment#docker-builds shows, and never from ARG or ENV. With Fly.io, deploy with `fly deploy --build-secret ADONISJS_PLUS_TOKEN=<token>`, and change the deploy step of a workflow that runs it.

6. Tell me to create one token for each place at https://plus.adonisjs.com/account/tokens, named after it, and to save each as ADONISJS_PLUS_TOKEN myself. Never ask me for a token, and never print one.
   - GitHub Actions: with the GitHub CLI, `gh secret set ADONISJS_PLUS_TOKEN`. Without it, https://github.com/<owner>/<repo>/settings/secrets/actions/new, with the name in "Name", the token in "Secret", then "Add secret".
   - Other CI providers and platforms: tell me where their settings keep secrets or environment variables.
   Wait until I say I did.

7. Tell me what you changed in each file. Then ask me: "Should I add and commit these changes?"

Add the token as a repository secret named ADONISJS_PLUS_TOKEN, in Settings → Secrets and variables → Actions. Then let actions/setup-node point the @adonisplus scope at the Plus registry. It writes a temporary .npmrc on the runner with the token, so your committed .npmrc stays as it is.

.github/workflows/ci.yml
steps:
  - uses: actions/checkout@v4

  - uses: actions/setup-node@v4
    with:
      node-version: 24
      registry-url: https://plus.adonisjs.com/registry/
      scope: '@adonisplus'

  - run: npm ci
    env: 
      NODE_AUTH_TOKEN: ${{ secrets.ADONISJS_PLUS_TOKEN }}

With Yarn, Yarn does not read .npmrc. Replace the env of the install step with a step before it, run: yarn config set --home npmScopes.adonisplus.npmAuthToken "$ADONISJS_PLUS_TOKEN", with env: ADONISJS_PLUS_TOKEN: ${{ secrets.ADONISJS_PLUS_TOKEN }}.

Add ADONISJS_PLUS_TOKEN as a secret in your provider's settings. Then add the token to .npmrc before the install, on a line of its own, and remove the file after it.

Terminal
printf '\n//plus.adonisjs.com/registry/:_authToken=%s\n' "$ADONISJS_PLUS_TOKEN" >> .npmrc && npm ci && rm -f .npmrc

With Yarn, which does not read .npmrc, run this before the install instead.

Terminal
yarn config set --home npmScopes.adonisplus.npmAuthToken "$ADONISJS_PLUS_TOKEN"

The secret's name must match exactly: ADONISJS_PLUS_TOKEN.

How you pass the token depends on whether the platform builds your app with Docker or with its own build system.

On platforms like Railway or Render, which run the install in their own build, add ADONISJS_PLUS_TOKEN as an environment variable in the platform's dashboard. Then use this as the install or build command.

Terminal
printf '\n//plus.adonisjs.com/registry/:_authToken=%s\n' "$ADONISJS_PLUS_TOKEN" >> .npmrc && npm ci && rm -f .npmrc

With Yarn, which does not read .npmrc, run this before the install instead.

Terminal
yarn config set --home npmScopes.adonisplus.npmAuthToken "$ADONISJS_PLUS_TOKEN"

The rm -f .npmrc removes the file with the token once the install ends. Some platforms cache the build folder between builds, and without it the token would stay there after you revoke it.

A Docker build does not see the host's environment variables. Pass the token as a BuildKit secret: the secret never reaches an image layer, and removing .npmrc in the same RUN keeps the written token out of the layer too.

Dockerfile
# syntax=docker/dockerfile:1
FROM node:24-alpine AS build
WORKDIR /app
COPY package*.json .npmrc ./

RUN --mount=type=secret,id=ADONISJS_PLUS_TOKEN \
    printf '\n//plus.adonisjs.com/registry/:_authToken=%s\n' "$(cat /run/secrets/ADONISJS_PLUS_TOKEN)" >> .npmrc \
    && npm ci \
    && rm -f .npmrc

COPY . .
RUN node ace build

FROM node:24-alpine
WORKDIR /app/build
# Copy the whole build stage, node_modules included, so the final stage installs nothing without the token.
COPY --from=build /app /app
CMD ["node", "bin/server.js"]

Pass the token when you build the image.

Terminal
docker build --secret id=ADONISJS_PLUS_TOKEN,env=ADONISJS_PLUS_TOKEN -t your-app .
Never pass the token with ARG or --build-arg. Build arguments are saved in the image history, and docker history shows them.

fly secrets set does not reach the Docker build. Deploy with --build-secret, which matches the --mount=type=secret,id=ADONISJS_PLUS_TOKEN of your Dockerfile.

Terminal
fly deploy --build-secret ADONISJS_PLUS_TOKEN=$ADONISJS_PLUS_TOKEN

Troubleshooting

What a 401 or a 404 during install means, and how to fix it.

Pull request reviews

Turn on the Flow review on your GitHub repositories.