Skip to content
private npm registry (Verdaccio) using gitlab-ce as authentication and authorization provider
TypeScript JavaScript Dockerfile
Branch: master
Clone or download
Latest commit ccafea2 Nov 20, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.vscode fix: flow Jun 21, 2018
bin chore: add functional tests Aug 22, 2018
conf feat: gitlab-11.2-group-api-improvements Aug 10, 2018
src feat: get rid of legacy mode Nov 17, 2019
test chore: remove warning Nov 11, 2019
.babelrc refactor: update dependencies and script Nov 5, 2019
.dockerignore refactor: docker build improvements Jul 20, 2018
.editorconfig refactor: add flow support to eslint configuration Jul 18, 2018
.eslintignore chore: fix lint issues Nov 5, 2019
.eslintrc chore: remove eclint Nov 11, 2019
.gitignore refactor: update dependencies Nov 4, 2019
.npmignore chore: build refactor and jest testing support Aug 17, 2018
.prettierrc chore: add prettier conf Nov 11, 2019
.travis.yml docs: updated Dec 7, 2018
Dockerfile chore(docker): update verdaccio dep to 4.0 Jun 26, 2019
LICENSE.txt feat: personal access token authentication Jan 7, 2018 docs: remove references to normal mode in readme Nov 19, 2019
docker-compose.yml feat: gitlab-11.2-group-api-improvements Aug 8, 2018
package.json chore(lint): add markdownlint, use lint instead of lint:ts witin ci Nov 18, 2019
tsconfig.json chore: migrating to typescript Jul 9, 2019
yarn.lock chore: upgrade commitlint and jest-environment-node Nov 18, 2019


Use GitLab Community Edition as authentication provider for the private npm registry Verdaccio, the sinopia fork.

npm build dependencies

The main goal and differences from other sinopia/verdaccio plugins are the following:

  • no admin token required
  • user authenticates with Personal Access Token
  • access & publish packages depending on user rights in gitlab

This is experimental!

Use it

You need at least node version 8.x.x, codename carbon.

git clone
cd verdaccio-gitlab
yarn install
yarn start

NOTE: Define http_proxy environment variable if you are behind a proxy.

Verdaccio is now up and running. In order the see this plugin in action, you can use the following Verdaccio configuration in your ~/.config/verdaccio/config.yaml.

# Verdaccio storage location relative to $HOME/.config/verdaccio
storage: ./storage




    # scoped packages
    access: $all
    publish: $authenticated
    proxy: npmjs
    gitlab: true

    access: $all
    publish: $authenticated
    proxy: npmjs
    gitlab: true

# Log level can be changed to info, http etc. for less verbose output
  - {type: stdout, format: pretty, level: debug}

Restart Verdaccio and authenticate into it with your credentials

using the Web UI http://localhost:4873 or via npm CLI:

yarn login --registry http://localhost:4873

and publish packages:

yarn publish --registry http://localhost:4873

Access Levels

Access and publish access rights are mapped following the rules below.

verdaccio-gitlab access control will only be applied to package sections that are marked with gitlab: true as in the configuration sample above. If you wish to disable gitlab authentication to any package config, just remove the element from the config.


access is allowed depending on the following verdaccio package configuration directives:

  • authenticated users are able to access all packages
  • unauthenticated users will be able to access packages marked with either $all or $anonymous access levels at the package group definition

Please note that no group or package name mapping is applied on access, any user successfully authenticated can access all packages.


publish is allowed if the package name matches the logged in user id, if the package name or scope of the package matches one of the user's groups, and the user has auth.gitlab.publish access rights on the group, or if the package name (possibly scoped) matches on the user's projects, and the user has auth.gitlab.publish access rights on the project.

For instance, assuming the following configuration:

  • auth.gitlab.publish = $maintainer
  • the gitlab user sample_user has access to group group1 as $maintainer and group2 as $reporter in gitlab and has access to project group3/project as $maintainer
  • then this user would be able to access any package
  • publish any of the following npm packages in verdaccio:
    • sample_user
    • group1
    • any package under @group1/**
    • @group3/project
    • error if the user tries to publish any package under @group2/**

Configuration Options

The full set of configuration options is:

    url: <url>
      enabled: <boolean>
      ttl: <integer>
    publish: <string>
Option Default Type Description
url <empty> url mandatory, the url of the gitlab server
authCache: enabled true boolean activate in-memory authentication cache
authCache: ttl 300 (0=unlimited) integer time-to-live of entries in the authentication cache, in seconds
publish $maintainer [$guest, $reporter, $developer, $maintainer, $owner] group minimum access level of the logged in user required for npm publish operations

Authentication Cache

In order to avoid too many authentication requests to the underlying gitlab instance, the plugin provides an in-memory cache that will save the detected groups of the users for a configurable ttl in seconds.

No clear-text password is saved in-memory, just an SHA-256 hash of the user+password, plus the groups information.

By default, the cache will be enabled and the credentials will be stored for 300 seconds. The ttl is checked on access, but there's also an internal timer that will check expired values regularly, so data of users not actively interacting with the system will also be eventually invalidated.

Please note that this implementation is in-memory and not multi-process; if the cluster module is used for starting several verdaccio processes, each process will store its own copy of the cache, so each user will actually be logged in multiple times.


git clone
cd verdaccio-gitlab
docker-compose up --build -d

The Dockerfile provides a default configuration file that is internally available under /verdaccio/conf/config.yaml. In order to overwrite this configuration you can provide your own file and mount it on docker startup with the --volume option, or equivalent mechanism (e.g. ConfigMaps on Kubernetes / OpenShift with the helm chart).

Create a Release

Run one of the following command to create a release:

yarn release:major
yarn release:minor
yarn release:patch

finally run

yarn publish

Flow Support

In order to support flow, flow-typed support files are installed in the repo. These are generated based on the dependencies of the project and committed to the repository.

Anytime the project dependencies change, run the following command to update the flow-typed support files:

# Just once in your environment
yarn global add flow-typed

flow-typed install

Functional Tests

In order to run functional tests with debug output, set the VERDACCIO_DEBUG=true environment variable, as documented by verdaccio:

VERDACCIO_DEBUG=true yarn test:functional

Inspired by



You can’t perform that action at this time.