> ## Documentation Index
> Fetch the complete documentation index at: https://www.mill.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Package registry setup

> Authenticate source builds to GitHub Packages.

Mill source builds use published, open-source packages from the `@avgeek-oss` scope. The repository's `.npmrc` maps that scope to GitHub Packages; other dependencies come from npm. No sibling checkout or unpublished library source is required. Published Mill images already contain these dependencies and need no npm credentials.

GitHub Packages requires authentication to install public npm packages. Use a GitHub classic personal access token with `read:packages`, following [GitHub's npm registry authentication guide](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#authenticating-to-github-packages).

## Local development and source builds

Log in once with your GitHub username and the token as the password:

```sh theme={"system"}
npm login --scope=@avgeek-oss --registry=https://npm.pkg.github.com --auth-type=legacy
node tools/with-package-token.mjs pnpm install --frozen-lockfile
```

npm stores that login in your user `.npmrc`, outside the repository. The wrapper also accepts `NODE_AUTH_TOKEN` from a secret manager or `NPM_CONFIG_USERCONFIG` pointing to a user configuration file. It creates an owner-only temporary npm configuration for the child command and removes it when the command finishes. Keep credentials outside the checkout and never commit them.

For a Docker source build, use the same wrapper. With bundled PostgreSQL, set the API's `DATABASE_URL` in `.env` to `postgres://mill:<POSTGRES_PASSWORD>@postgres:5432/mill`, using the actual password generated by `init-env`. The `127.0.0.1:55432` development URL is for Node running on the host, not for the API container:

```sh theme={"system"}
node tools/init-env.mjs
# Edit .env: use postgres:5432 in DATABASE_URL for this container build.
node tools/with-package-token.mjs docker compose --project-name mill --env-file .env --file docker-compose.yml --file docker-compose.postgres.yml --file tools/compose-source.yml up --build --detach --wait
```

The optional PostgreSQL overlay supplies the contributor database; omit it if you supply your own connection URL. The source-build overlay builds separate `api` and `web` targets and sends `NODE_AUTH_TOKEN` as the `npm_token` BuildKit secret. The Dockerfile creates the npm configuration in a temporary filesystem only during dependency installation. It does not use a token build argument or runtime environment variable. The default Compose file is image-only and needs no npm token. See [Docker's build secret documentation](https://docs.docker.com/build/building/secrets/).

For a direct Docker build, run:

```sh theme={"system"}
node tools/with-package-token.mjs docker build --secret id=npm_token,env=NODE_AUTH_TOKEN --target api --tag mill-api:local .
node tools/with-package-token.mjs docker build --secret id=npm_token,env=NODE_AUTH_TOKEN --target web --tag mill-web:local .
```

The production verification runner resolves the same credentials automatically:

```sh theme={"system"}
node tools/production-verify.mjs
```

## Continuous integration

The verify jobs configure `actions/setup-node` for the scoped registry and pass the job's `GITHUB_TOKEN` to the install step as `NODE_AUTH_TOKEN`. Source verification, review-artifact builds, and release-image builds pass it to BuildKit. Workflows request `packages:read` where needed, and reusable workflow callers preserve that permission.

The shared package's **Manage Actions access** settings must grant `avgeek-oss/mill` read access. Adding the permission to a workflow does not grant access to a different repository's package by itself. A package maintainer must configure that grant; see [GitHub's package access guidance](https://docs.github.com/en/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility#ensuring-workflow-access-to-your-package).

An authentication or access failure should fail installation. Do not copy the library into Mill, disable the install gate, or commit a replacement token. CI does not publish the design system or require package write permission.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.