Skip to main content

Registry authentication

Acromedia packages are served from a private GitLab registry. Authentication is required before pnpm dlx, pnpm install, or other package-resolution commands can download them.

Ask a maintainer to confirm that your own GitLab account has package access. A human must then create their own personal GitLab access token with the api scope. Never use another person's token.

Store the registry configuration in your home ~/.npmrc so it is available across projects:

@acromedia:registry=https://git.acromedia.com/api/v4/packages/npm/
//git.acromedia.com/api/v4/packages/npm/:_authToken=${GITLAB_PACKAGE_TOKEN}

Set GITLAB_PACKAGE_TOKEN in your shell or secret manager. The value in .npmrc must be exactly ${ENV_VAR} for environment resolution; surrounding text is treated as a literal token. A literal token value also works, but a home-level file or an environment reference is safer than storing a secret in a project.

warning

Never share or commit a token. Do not put a literal token in a tracked .npmrc. Keep environment-variable values out of committed files and CI logs.

Optional project configuration​

A project .npmrc can contain the same registry mapping and token assignment when project-specific configuration is necessary. Keep it untracked if it contains a literal secret.

The CLI's create and health checks inspect, in order:

  1. .npmrc in the current project directory
  2. ~/.npmrc

The first usable token assignment makes the check pass. A missing, empty, commented, placeholder, or unresolved environment-variable assignment is not usable, so inspection continues to the home file. Recognized placeholders include values such as PASTE-YOUR-GITLAB-TOKEN-HERE, YOUR_TOKEN, and <token>.

If either file cannot be read, the CLI continues looking for usable configuration in the other file. If none is found, it reports the first unreadable file and asks you to restore access rather than recommending a new token.

What the check proves​

This is a configuration-presence check. It recognizes a non-placeholder GitLab _authToken assignment; it does not contact GitLab, validate token scope or expiry, prove package access, or validate the registry mapping. If installation still fails, verify the registry URL, environment-variable value, account access, token scope, and token expiry without printing the secret.

Generated projects​

gesso create inspects authentication in the directory where it is run, before generating the target. A project .npmrc in that source directory is not copied into the generated prototype. pnpm install inside the new directory therefore needs authentication available there, normally through the recommended home ~/.npmrc.

The prototype includes an untracked .npmrc.example for the exceptional case where project-local configuration is needed. Copy it to .npmrc, replace its placeholder, and keep .npmrc untracked. Prefer an environment-variable reference over a literal token.