# CI and deployment

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

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

Open [Tokens](/account/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

::agent-prompt
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?"
```
::

## CI

### 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.

```yaml [.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/ # [!code ++]
      scope: '@adonisplus' # [!code ++]

  - run: npm ci
    env: # [!code ++]
      NODE_AUTH_TOKEN: ${{ secrets.ADONISJS_PLUS_TOKEN }} # [!code ++]
```

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

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.

```sh
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.

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

The secret's name must match exactly: `ADONISJS_PLUS_TOKEN`.

## 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

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.

```sh
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.

```sh
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

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 [Dockerfile]
# syntax=docker/dockerfile:1
FROM node:24-alpine AS build
WORKDIR /app
COPY package*.json .npmrc ./

# [!code highlight:4]
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.

```sh
docker build --secret id=ADONISJS_PLUS_TOKEN,env=ADONISJS_PLUS_TOKEN -t your-app .
```

:::tip
Never pass the token with `ARG` or `--build-arg`. Build arguments are saved in the image history, and `docker history` shows them.
:::

### Fly.io

`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.

```sh
fly deploy --build-secret ADONISJS_PLUS_TOKEN=$ADONISJS_PLUS_TOKEN
```

## Next steps

::card-group
:::card{title="Troubleshooting" to="/docs/get-started/troubleshooting"}
What a 401 or a 404 during install means, and how to fix it.
:::

:::card{title="Pull request reviews" to="/docs/flow/reviews/setup"}
Turn on the Flow review on your GitHub repositories.
:::
::
