npm / npm/documentation

Trusted Publisher: GitLab CI/CD namespace field docs unclear for nested subgroups, UI accepts invalid config silently

Open
#1,901 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
MDX
Stars
712
Forks
4.2k
Avg merge
4d 16h
Merged PRs (30d)
3

Description

Summary

When configuring a Trusted Publisher for GitLab CI/CD on npmjs.com, the "Namespace" field is described as "Your
GitLab username or group name." For projects nested under subgroups (e.g., gitlab.com/org/sub1/sub2/project),
it's unclear that the full subgroup path must be entered as the namespace. The UI accepts an incorrect split
between namespace and project without validation, resulting in a confusing 404 error during OIDC token exchange
at publish time.

Steps to Reproduce

  1. Have a GitLab project at a nested path: gitlab.com/conbo_harbour/apps/storybook/storybook.components
  2. Go to npmjs.com → package → Settings → Trusted Publishers → Add GitLab CI/CD
  3. Enter conbo_harbour as Namespace and apps/storybook/storybook.components as Project (this seems logical —
    top-level group as namespace, rest as project path)
  4. The UI accepts this without any warning
  5. Run npm publish --provenance from GitLab CI with a valid NPM_ID_TOKEN

Expected Behavior

Either:

  • The UI should validate or hint that namespace must be the full group path including subgroups (i.e.,
    conbo_harbour/apps/storybook) and project must be only the project name (storybook.components)
  • Or the documentation should clearly explain this with a subgroup example

Actual Behavior

npm publish fails with:

POST 404 https://registry.npmjs.org/-/npm/v1/oidc/token/exchange/package/@conboai%2fstorybook.components
OIDC token exchange error - package not found
npm error code ENEEDAUTH

This is because GitLab's OIDC token contains namespace_path: conbo_harbour/apps/storybook, which doesn't match
the configured namespace conbo_harbour.

Correct Configuration

For a project at gitlab.com/conbo_harbour/apps/storybook/storybook.components:

  ┌───────────┬──────────────────────────────┐
  │   Field   │        Correct value         │
  ├───────────┼──────────────────────────────┤
  │ Namespace │ conbo_harbour/apps/storybook │
  ├───────────┼──────────────────────────────┤
  │ Project   │ storybook.components         │
  └───────────┴──────────────────────────────┘

Suggestions

  1. Update the Namespace field description from "Your GitLab username or group name" to "Your full GitLab group
    path, including subgroups (e.g., my-org/team/sub-team)"
  2. Add a nested subgroup example to the https://docs.npmjs.com/trusted-publishers/
  3. Ideally, validate the namespace/project combination against GitLab's OIDC claim format before saving

Environment

  • GitLab.com shared runners
  • GitLab project path: conbo_harbour/apps/storybook/storybook.components

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the Trusted Publishers documentation at https://docs.npmjs.com/trusted-publishers/ and review the GitLab CI/CD Namespace and Project field descriptions. Clarify that Namespace uses the full GitLab group path for nested subgroups, and add the issue's nested-path example. Done when the documented values distinguish the subgroup path from the project name.

Written by the indexing model from the issue text.

Assessment

Tech stack
gitlab
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.