verdaccio-gitlab

A Verdaccio auth plugin for logging in via a GitLab Personal Access Token (PAT) and strictly restricting package access based on membership in specified groups or subgroups.

Users log into Verdaccio using their GitLab username and provide their PAT instead of a password. The plugin verifies the user via GET /user, then fetches their group list via GET /groups, and only allows those who are members of at least one group defined in allowedGroups. For package operations, allow_access, allow_publish, and allow_unpublish are additionally implemented, meaning anonymous users and users outside the GitLab group gate will not gain access, even if access: $all is configured.

Installation

npm install
npm run build

After building, place the package in the Verdaccio plugins directory or install it globally next to Verdaccio.

Verdaccio Configuration

auth:
  gitlab:
    gitlabUrl: https://gitlab.example.com
    allowedGroups:
      - platform
      - frontend/packages
    allowSubgroups: true
    minAccessLevel: reporter
    cacheTtlSeconds: 300

packages:
  '@*/*':
    access: $all
    publish: $authenticated
    unpublish: $authenticated

  '**':
    access: $all
    publish: $authenticated
    unpublish: $authenticated

access: $all here is safe solely because the plugin first enforces its own gate. If the user is not in the allowed GitLab groups, allow_access will return false.

Options

| Option | Default | Description | | --- | --- | --- | | gitlabUrl | https://gitlab.com | The base GitLab URL. | | apiBaseUrl | ${gitlabUrl}/api/v4 | Full API URL if a custom path is required. | | allowedGroups | [] | Allowed groups, subgroups, or group IDs. An empty list denies everyone. | | allowSubgroups | true | Allows platform to match platform/frontend. | | minAccessLevel | unset | Minimum GitLab access level: guest, reporter, developer, maintainer, owner, or a numeric value. | | enforceUsernameMatch | true | The Verdaccio username must match the GitLab username from the PAT. | | cacheTtlSeconds | 300 | How often to re-verify GitLab membership during package access. | | storeTokens | true | Keep PAT in process memory for membership re-verification. It is not written to disk. | | requireActiveSession | true | After a Verdaccio restart, old Verdaccio tokens won't work until a new login. | | groupNamePrefix | gitlab: | Prefix for groups returned to Verdaccio. | | gateGroup | gitlab:allowed | Internal group required for package operations. Without it, access is denied. | | extraGroups | [] | Additional Verdaccio groups for successfully authenticated GitLab users. | | requestTimeoutMs | 10000 | Timeout for GitLab API requests. | | maxPages | 100 | Maximum number of pages when fetching GitLab groups. |

For a PAT, the read_api scope is usually sufficient. If your GitLab instance does not allow reading groups with it, use the api scope instead.

Groups in package rules

The plugin returns groups to Verdaccio in the format gitlab:<full_path>. This allows you to create more granular rules on top of the general gate:

packages:
  '@frontend/*':
    access: gitlab:frontend/packages
    publish: gitlab:frontend/packages

If GitLab returns the group frontend/packages, the user will receive the gitlab:frontend/packages group in Verdaccio.

Why not a middleware

Verdaccio middleware plugins are registered after the built-in endpoints, meaning they cannot reliably replace the standard npm API access checks. The correct extension point for this requirement is an auth plugin implementing authenticate, allow_access, allow_publish, and allow_unpublish.