In GitLab's package registry, why must npm, Maven and PyPI packages publish to a project, even when consumers install from group or instance endpoints?
answer
- a package belongs to one project
- group and instance endpoints aggregate
- instance npm needs a scope
- PyPI stops at the group
basics
~20 sEvery package is stored in, and permissioned by, one project, so npm, Maven and PyPI publish only to the project endpoint. Group and instance endpoints are read views that aggregate those projects, with naming rules for the instance level.
solid answer
~40 sA package in GitLab's package registry lives in exactly one project: that project's permissions, protection rules and deletion apply to it. So npm, Maven and PyPI publish only to `/api/v4/projects/<project_id>/packages/<format>`. Installing can use wider endpoints that aggregate many projects: the group endpoint `/api/v4/groups/<group_id>/-/packages/<format>` for npm, Maven and PyPI, and the instance endpoint `/api/v4/packages/<format>` for npm and Maven but not PyPI. The instance level only finds packages whose names map back to a project: npm packages must be scoped with the root namespace (`@acme/...`), and a Maven package must have the same path as its project. A team therefore publishes from each project's pipeline with `CI_JOB_TOKEN` and gives consumers one group or instance URL.
code
ini · 3 lines; .npmrc next to package.json, publishing @acme/analytics-client to its project
@acme:registry=https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/
//gitlab.example.com/api/v4/projects/<project_id>/packages/npm/:_authToken=${NPM_TOKEN}go deeper
Recall that packages are published to a project and that the URL contains packages followed by the format name. Know the three levels: project, group, instance.
Explain which levels allow install for npm, Maven and PyPI, the instance-level npm scope rule, and how a pipeline publishes with the job token.
Design the layout so consumers use one group or instance URL while each package keeps one owning project, and handle duplicates and forwarding to avoid dependency confusion.
Decide where package ownership lives in the group hierarchy. One root namespace scope gives a clean instance-wide catalogue but couples package names to the organisation's top-level structure.
## A package always has a home project GitLab's **package registry** stores packages for many formats (npm, Maven, PyPI, Helm, NuGet, generic and more). Whatever the format, each package is stored **in one project**. That project decides: - who may publish and delete (by role, and through **package protection rules**); - which token types are valid; - what storage the package counts against. Because ownership is per project, the write path is per project too. The documentation's publishing matrix shows npm, Maven (with `mvn` or `gradle`) and PyPI as **publishable to a project only**, never to a group or the instance. ## The three endpoint levels | Level | URL shape | npm | Maven | PyPI | |---|---|---|---|---| | Project | `/api/v4/projects/<project_id>/packages/<format>` | publish and install | publish and install | publish and install | | Group | `/api/v4/groups/<group_id>/-/packages/<format>` | install | install | install | | Instance | `/api/v4/packages/<format>` | install | install | not available | The group and instance endpoints are **read aggregations**. A PyPI package published to a project in a group is also visible through the group's index, and an npm or Maven package can be found at the instance level if its name follows the naming rule below. Which one to install from: 1. **Project** — few packages, not in one group. 2. **Group** — many packages across projects in the same group or subgroup. 3. **Instance** — many packages across groups (npm and Maven only). ## Naming rules that make the wider endpoints work The instance endpoint has no project ID in its URL, so GitLab has to find the project from the package name. - **npm.** To install from the instance, the package must be **scoped**, and the scope must be the **root namespace of the project that hosts the package**, in lowercase. A package hosted in `acme/engineering/analytics` is named `@acme/analytics-client`. Group and project endpoints do not need this convention. - **Maven.** The instance endpoint exposes only packages whose path matches the project path, which in `pom.xml` means a `groupId` like `group-slug.subgroup-slug` and an `artifactId` equal to the project slug. If the same npm name and version exist in several projects, an install through an aggregating endpoint gets the most recently published one, which is another reason to keep one owner per package name. ## Publishing from a pipeline From CI/CD, publish with the **job token**: the npm documentation writes a project-scoped `.npmrc` in the job using `${CI_SERVER_HOST}`, `${CI_PROJECT_ID}` and `${CI_JOB_TOKEN}`, then runs `npm publish`. For Maven, the `settings.xml` server entry carries an HTTP header whose name matches the token type: | Token | Header name | |---|---| | Personal access token | `Private-Token` | | Deploy token | `Deploy-Token` | | CI/CD job token | `Job-Token` | From a laptop, use a personal access token (npm requires the `api` scope) or a deploy token with `read_package_registry` and `write_package_registry`. ## Pointing consumers at the wider endpoints Consumers only change the URL they read from; the package's home project stays the same: - **npm** maps the scope to the group or instance URL, for example `@acme:registry=https://gitlab.example.com/api/v4/packages/npm/`, plus an `_authToken` line for that path. - **pip** uses the group's simple index, `.../api/v4/groups/<group_id>/-/packages/pypi/simple`, as its `--index-url`, with the token in the URL or in a `.netrc` entry. - **Maven** lists the group or instance URL in the `repositories` section of `pom.xml`, while `distributionManagement` keeps the project URL for publishing. One read URL per team means a new project's packages show up without any consumer changing configuration. ## Duplicates and forwarding Two settings change what a consumer actually receives: - **Duplicates.** By default npm and PyPI refuse a second upload of the same name and version; Maven allows duplicates unless a group Owner turns off **Allow duplicates** in the group's **Duplicate packages** settings. - **Request forwarding.** When a package is missing from GitLab, npm and PyPI requests are forwarded to the public registry by default, while Maven forwarding is off by default. The documentation lists the forwarding controls for Premium and Ultimate, where group Owners can clear **Forward npm package requests** and **Forward PyPI package requests**. Forwarding is why deleting an internal package can let a public package with the same name be installed instead, a dependency-confusion risk. ## Typical mistakes - Pointing `npm publish` at the group or instance URL and getting an error, because writes go to a project. - Naming an npm package after the project rather than the root namespace, then wondering why the instance endpoint cannot find it. - Expecting `pip install` from an instance-wide URL; PyPI stops at the group. - Leaving forwarding on for private package names that could be registered publicly.
- In GitLab, why can deleting an internal npm package let a different package be installed under the same name?When a package is not found, npm and PyPI requests can be forwarded to the public registry. After deletion, an install of that name and version may resolve to a public package with the same name, which could be malicious. Before deleting, confirm nothing uses it and turn off forwarding for the group.
- In GitLab, what must a Maven package look like to be installable through the instance-level endpoint?Its path must match its project's path: in `pom.xml` the `groupId` reflects the group and subgroup slugs and the `artifactId` is the project slug. A package whose coordinates do not match its project is still available through the project and group endpoints, but not the instance one.
- You can publish npm packages directly to a group endpoint.
- Any npm package name is installable from the instance endpoint.
- PyPI packages can be installed from an instance-wide index.
- The npm scope should match the project name, not the root namespace.
- Forwarding to the public registry is harmless once an internal package is deleted.