GitLab CI/CD Publish to the Package Registry (npm, Maven, generic) Prompt

You are a senior CI/CD engineer who has standardized internal package
distribution across dozens of repos using the GitLab Package Registry.

I will provide:
- The package ecosystem(s) I need to publish: npm, Maven/Gradle, PyPI, NuGet, or generic files
- Where the package should live: project-level vs group-level registry
- My versioning scheme (SemVer tags, conventional commits, or manual) and my default branch/tag protection rules
- How consumers install today (public npm, an internal Nexus/Artifactory, nothing yet)

Your job:

1. **Pick the auth model** — explain when `CI_JOB_TOKEN` is sufficient (publishing to the same project/group the pipeline runs in), when a **project/group deploy token** or **CI/CD variable** is required (cross-project or cross-group consumption), and the exact scopes each needs (`read_package_registry`, `write_package_registry`).

2. **Write the publish job** — produce a real, valid `.gitlab-ci.yml` `publish` job for my ecosystem:
   - **npm**: generate `.npmrc` at job time pointing the scope to `${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/npm/` with `//...:_authToken=${CI_JOB_TOKEN}`, then `npm publish`.
   - **Maven/Gradle**: configure `settings.xml`/`repositories` with the `${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/maven` endpoint and `Job-Token` header auth.
   - **generic**: `curl --header "JOB-TOKEN: $CI_JOB_TOKEN" --upload-file` to the generic packages API with a versioned path.

3. **Gate the version** — only publish on a protected tag or a release event, and fail fast if the package version in the manifest does not match the git tag (drift check). Show the `rules:` that scope publishing to `$CI_COMMIT_TAG` and skip it on MRs.

4. **Handle immutability & duplicates** — explain the registry's duplicate-version behavior per ecosystem, how to enable/disable duplicate rejection, and why re-publishing the same version should be a hard error, not a silent overwrite.

5. **Wire the consumer side** — give the install/config snippet a downstream project or developer uses to pull the package (scoped `.npmrc`, Maven repository block, or `pip install --index-url`), using a deploy token or `CI_JOB_TOKEN` with `read` scope.

6. **Failure modes** — cover `401 Unauthorized` (wrong/expired token, missing scope), `403 Forbidden` (publishing from an unprotected ref), version/name mismatch rejections, and the "package already exists" 400.

Output: (a) the complete `.gitlab-ci.yml` publish job with `rules:` and the auth setup inline, (b) the version-drift guard script, (c) the consumer install config, (d) a short table of the top failure modes and the exact error each returns.

Bias toward: `CI_JOB_TOKEN` over long-lived tokens, publishing only from protected tags, one immutable version per release, and a manifest-vs-tag drift check that fails the pipeline before upload.