Skip to content

Add support for PAT to NPM registry

Problem to solve

The GitLab NPM Registry allows Javascript developers to build, publish and version their NPM packages to their GitLab instance. However, NPM requires users to authenticate with OAuth and since the GitLab personal access token does not support OAuth, users are forced to generate their own token (outside of GitLab) in order to use the registry, which is not a scalable solution for our enterprise customers. In addition, this prevents users from using two-factor authentication for their GitLab accounts.

Issue https://gitlab.com/gitlab-org/gitlab-ce/issues/63438 adds OAuth2 support to the personal access token. Now we will add support authentication via personal access token for the NPM Registry.

Intended users

Proposal

Allow users to authenticate to the NPM Registry using their GitLab personal access token, which with the completion of https://gitlab.com/gitlab-org/gitlab-ce/issues/63438 now supports OAuth.

Further details

Use cases

  1. A Javascript (node.js) developer at a Premium customer wants to start using GitLab as their NPM Registry.
  2. Since the feature is enabled at the instance level, the developer can easily enable the feature at the project level by navigating to Settings->General->Permissions and enabling 'Packages'
  3. They click on 'Packages' and see the empty state page that directs them to the NPM documentation
  4. They see an updated version of this section of documentation that documents how to authenticate to the NPM registry using their personal access token, which now supports OAuth2.
  5. They then generate a personal access token by navigating to their User Settings menu and selecting Access Tokens.
  6. They choose a name and optional expiry date for the token.
  7. They choose the desired scopes.
  8. They click the Create personal access token button.
  9. They save the personal access token somewhere safe, since once they leave or refresh the page they won’t be able to access it again.
  10. The developer then modifies their .npmrc file to point to the NPM Registry and authenticate with their new OAuth enabled personal access token.
  11. The developer then specifies the GitLab registry for NPM by updating their package.json file specify the registry for NPM
  12. Finally, they start pushing their NPM packages to the GitLab NPM Registry.

Sample .npmrc

; Set URL for your scoped packages.
; For example package with name `@foo/bar` will use this URL for download
@foo:registry=https://gitlab.com/api/v4/packages/npm/

; Add the OAuth token for the scoped packages URL. This will allow you to download
; `@foo/` packages from private projects.
//gitlab.com/api/v4/packages/npm/:_Authorization: Bearer $TOKEN>

; Add OAuth token for uploading to the registry. Replace <your_project_id>
; with the project you want your package to be uploaded to.
//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_Authorization: Bearer $TOKEN>

Benefits

  • Allow users to use the NPM Registry and still leverage two-factor authentication
  • Bring the NPM Registry closer in feature parity to the Maven Repository.
  • First step in adding OAuth support to all GitLab tokens

Permissions and Security

The permissions should remain the same. At the instance level, any user can view and download packages. But, only developers with permission to the project can upload and delete them.

Action Guest Reporter Developer Maintainer Owner
Pull from Maven repository or NPM registry or Conan Repository x x x x
Publish to Maven repository or NPM registry or Conan Repository x x x

Documentation

Testing

  • Test that we avoid collisions and do not authenticate doorkeeper tokens as PATs and vice-versa.
  • Test that the new PAT works with the NPM Registry.

What does success look like, and how can we measure that?

Metrics to collect

Category Metric Aggregated by SMAU Eligible?
Package Registry # of page views of /packages
  • Time: day/week/month/quarter/year
  • Instance: Self-managed CE/Self-managed EE
  • Account type: Core/Starter/Premium/Ultimate
 Yes
Package Registry # of page views of /packages/*
  • NOTE: clicking on a specific package will take you to a URL like: https://gitlab.com/gitlabpackage/mavenfornewbies/-/packages/14666 we should count any visit and aggregate them under /packages/details
  • Time: day/week/month/quarter/year
  • Instance: Self-managed CE/Self-managed EE
  • Account type: Core/Starter/Premium/Ultimate
 Yes
Package Registry # of unique users that visit /packages
  • Time: day/week/month/quarter/year
  • Instance: Self-managed CE/Self-managed EE
  • Account type: Core/Starter/Premium/Ultimate
 Yes
Package Registry # of npm push events to the Maven Repository
  • Time: day/week/month/quarter/year
  • Instance: Self-managed CE/Self-managed EE
  • Account type: Core/Starter/Premium/Ultimate
 Yes
Package Registry # of packages deleted from the UI
  • Time: day/week/month/quarter/year
  • Instance: Self-managed CE/Self-managed EE
  • Account type: Core/Starter/Premium/Ultimate
 Yes

Success

Success looks like we have unblocked our users from using the NPM Registry. We can measure this by reaching out to our customers that have requested this feature and seeing if they are unblocked.

What is the type of buyer?

This feature will be focused on Director and Executives, as it is a Premium/Silver and Ultimate/Gold feature. https://about.gitlab.com/handbook/ceo/pricing/#four-tiers

Links / references

Edited by Tim Rizzi