CI and deployment
On this page
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
Overview
Section titled "Overview"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.
Create a token
Section titled "Create a token"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.
Let your agent set it up
Section titled "Let your agent set it up"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.
GitHub Actions
Section titled "GitHub Actions"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.
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 }}.
Other CI providers
Section titled "Other CI providers"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.
printf '\n//plus.adonisjs.com/registry/:_authToken=%s\n' "$ADONISJS_PLUS_TOKEN" >> .npmrc && npm ci && rm -f .npmrcWith Yarn, which does not read .npmrc, run this before the install instead.
yarn config set --home npmScopes.adonisplus.npmAuthToken "$ADONISJS_PLUS_TOKEN"The secret's name must match exactly: ADONISJS_PLUS_TOKEN.
Deployment
Section titled "Deployment"How you pass the token depends on whether the platform builds your app with Docker or with its own build system.
Platforms without Docker
Section titled "Platforms without Docker"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.
printf '\n//plus.adonisjs.com/registry/:_authToken=%s\n' "$ADONISJS_PLUS_TOKEN" >> .npmrc && npm ci && rm -f .npmrcWith Yarn, which does not read .npmrc, run this before the install instead.
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.
Docker builds
Section titled "Docker builds"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.
# 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.
docker build --secret id=ADONISJS_PLUS_TOKEN,env=ADONISJS_PLUS_TOKEN -t your-app .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.
fly deploy --build-secret ADONISJS_PLUS_TOKEN=$ADONISJS_PLUS_TOKEN