Package registries

Overview

Publish private npm, Cargo and PyPI packages to a group and install them with the tools you already have. npm publish, cargo publish and twine upload all work against a Gitmoap registry, and npm install, cargo build and pip install read from it — authenticated with the same access token as the rest of the platform, authorized by the same group membership, and charged against the same storage budget as the group's repositories.

A registry belongs to a group, not to a repository, which is what makes it usable across an organisation: the people who can see a group's code are the people who can install its packages, and a monorepo publishing twelve packages needs no extra plumbing. There is nothing to create — a registry starts existing the first time somebody publishes to it.

Quick start

Before you start

How it works

One registry per group and per format

A group has up to three registries — one for each ecosystem it speaks — and they are independent of each other. These are the URLs you point a tool at, with the group's id substituted in:

Inside a registry, everything hangs off the package name in a fixed shape. The management endpoints address the package and the version; the file is the level a download names:

A published version is immutable

A (package, version, filename) coordinate can be written once. Publishing the identical bytes to a coordinate that already holds them succeeds and changes nothing — which is what makes a retried CI job safe. Publishing different bytes to a coordinate that is taken is refused with 409 CONFLICT, and nothing about the stored version moves.

Where the tool declares a digest, it is checked against the bytes received before anything is stored: npm's SHA-512 integrity string and its SHA-1 shasum, and the sha256_digest twine sends with each file. A digest that does not match is 400 BAD_REQUEST, and the artifact is discarded. cargo publish declares nothing, so the SHA-256 recorded in the index is computed here from the bytes that arrived — and that computed checksum is what Cargo verifies every later download against.

Yank hides a version, delete destroys it

The two are not variations on the same idea.

Yank is the right answer for a bad release: it stops the version being picked up by anything new without breaking anyone who already depends on it. Delete is for bytes that must genuinely stop existing.

Names are normalised per ecosystem

Each format has its own idea of what two names being "the same" means, and Gitmoap stores each name the way that format expects. This is the name the management endpoints take, so it is worth knowing:

A name may be 1–214 characters of A–Z a–z 0–9 . _ - @ /, may not contain .., and may not start with - or / or end with /. A version is 1–128 characters of A–Z a–z 0–9 . _ + ! -, which covers both semver and PEP 440. A distribution filename is 1–255 characters of A–Z a–z 0–9 . _ + -, so it can carry no path separator and no ... Neither a version nor a filename may start with -.

Downloads are redirects

Fetching a tarball, a .crate or a wheel answers 302 with a URL to the bytes, so the file never travels through the API itself. Every package manager follows that automatically; a hand-written HTTP client has to be told to (curl -L). The URL it redirects to is good for five minutes, so it is not something to cache in a config file or paste into a ticket.

Your token rides whichever header the tool sends

Each ecosystem's client authenticates differently, and all three carriers are accepted. You never convert a token into anything — the same gmp_/gms_ string goes in all three places.

A registry serves only what you publish to it

It holds your packages and nothing else — it does not mirror or proxy npmjs.com, crates.io or PyPI. Keep the public registry configured alongside it and route only your own names to Gitmoap: an npm scope mapping, a named Cargo registry, an extra index for pip. Replacing the public default outright means every third-party dependency stops resolving.

Every write is on the record

Publishing, yanking, unyanking and deleting are recorded in the owning group's audit log, with the person or service account that did it. Reads are not — installing a package leaves no audit entry, so the log answers "who shipped this version" and "who removed it", never "who consumed it".

How to

Publish an npm package

Map your scope to the registry and put the token beside it. In the project's .npmrc:

Then npm publish from the package directory. The dist-tag is set at publish time — npm publish --tag beta files the version under beta instead of latest. The tag map a package advertises is exactly the one its most recent publish sent, so a publish under --tag beta leaves beta as the only tag the package carries until the next ordinary publish puts latest back. Standalone npm dist-tag and npm unpublish are not part of the surface: tags are set by publishing, and removal goes through the management endpoints below.

Install npm packages from your registry

A consumer needs the same two .npmrc lines. A machine that only installs should use a service-account token minted with package:read alone, so a leaked CI secret cannot publish.

Resolution then works as usual: npm asks for the package document, picks a version, and follows the tarball URL in it. That document carries the tag map, every published version's manifest and each version's publish time. The tarball URLs Gitmoap hands back always point at Gitmoap, whatever was in the tarball's own metadata when it was published.

To pull one specific tarball without npm — a checksum audit, a mirror script — request it directly and follow the redirect:

Search the npm registry

npm search --registry=<your registry URL> <text> works against a Gitmoap registry. Matching is by word and by substring, so serde_j finds serde_json — package names are identifiers, not prose, and a word-stemming search would miss that. Results page by offset, up to 100 at a time.

npm's wire format carries a score block, and the values in it are fixed placeholders rather than measurements — quality, popularity and maintenance are npmjs.com heuristics over download counts and public-repository signals a private registry has no source for. They say nothing about your packages, so read the names and versions and ignore the numbers beside them.

Publish a crate

Declare the registry in .cargo/config.toml, note the sparse+ prefix:

Supply the token as CARGO_REGISTRIES_GITMOAP_TOKEN, or store it with cargo login --registry gitmoap. Then cargo publish --registry gitmoap.

The crate name is lowercased when it is stored, so My_Crate and my_crate are one crate — and publishing the same version under both spellings conflicts, because the second .crate file will not be byte-identical to the first.

Depend on a crate from your registry

With the registry declared as above, a dependency names it:

Cargo reads the registry's configuration document first to learn where to download crate files from, where to send publishes and yanks, and whether it needs to send credentials at all. For a private or internal group that document says authentication is required and Cargo sends your token with index and download requests as well as with publish; for a public group it says none is required, and anyone can depend on the crate with no token configured.

Check what Cargo sees for a crate

The index is one line of JSON per published version, including the dependency list and the yanked flag. Reading it directly is the fastest way to answer "why did resolution pick that version" without a build.

Which URL serves a crate depends on the length of its name, following the sparse-registry layout: a name of three characters or more lives under two prefix segments (se/rd/serde), and a one- or two-character name lives under a single one (2/rs).

For a crate whose name is one or two characters:

To pull the crate file itself, request the download and follow the redirect:

Yank a crate version

cargo yank --registry gitmoap --version 1.2.3 acme-core marks a version so that no new resolution picks it, while every build that already pinned it keeps working. Nothing is deleted and no storage is freed. Yanking a version that is already yanked changes nothing and still succeeds.

Restore a yanked crate version

cargo yank --undo --registry gitmoap --version 1.2.3 acme-core puts the version back into resolution. Because a yank never removed anything, this is a complete restoration.

Search the Cargo registry

cargo search --registry gitmoap <query> searches the group's crates by word and by substring. Cargo pages by 1-based page number rather than by cursor, up to 100 results per page, because that is what the protocol specifies.

Publish a Python distribution

Add the repository to ~/.pypirc. The token goes in the password; the username is not what authenticates you, and __token__ is the convention:

Then twine upload --repository gitmoap dist/*. Twine sends one file per request, so an sdist and a wheel are two separate publishes and either can succeed while the other fails.

The project name is normalised the PEP 503 way, so My_Package.Core, my-package-core and MY.PACKAGE.CORE are all the same project.

Install Python packages from your registry

Point pip at the project index and give it the credentials inline. In pip.conf or pip.ini:

The project page lists every distribution file for the project with its SHA-256 attached, which is what pip verifies each download against. It is served as HTML or as JSON depending on what your client asks for, so both a modern resolver and an old one work unchanged.

List every Python project in a registry

The simple index is the group's PyPI project list — what a resolver walks and what a mirror script starts from. It comes back as HTML for an ordinary client and as JSON for one that asks for it, and it lists every project in the group's PyPI registry, alphabetically, in one response: the simple index has no pages, so nothing is left for a second request.

Download one distribution file

Request the file and follow the redirect. Each file's URL carries its project, version and filename, so it is stable and reproducible.

See what a group has published

The management listing spans all three formats and reports, per package, its latest version, how many versions it has, how many bytes it occupies and when it last changed. Packages come back most-recently-changed first. Pass a format to page through that one ecosystem with the cursor; omit it and you get a single overview page — up to 100 packages per format, with no cursor to continue from.

Latest version means the version published most recently, not the highest one. Publishing 1.0.1 as a patch after 2.0.0 is already out makes 1.0.1 the latest version the listing reports.

Inspect a package and its versions

The detail view is the one place that shows every version of a package with its size, whether it is yanked, when it was published and by whom — including publishes made by a service account from a pipeline.

Delete one version

Address the package by the name you published: the delete normalises it the way its format does, so My_Package.Core and my-package-core reach the same PyPI project and My_Crate reaches my_crate. npm is the exception, because npm names are stored exactly as they were published — there the case has to match. The bytes are released back to the namespace's storage budget as part of the delete.

Deleting the last version of a package leaves the package itself in the listing with no versions left in it. Delete the package to take it out of the list.

Delete a package and every version of it

Reference

The first-party management surface — the endpoints behind the Packages view, and the ones to script against:

The npm protocol surface. These are the shapes npm itself calls; you rarely invoke them by hand:

The Cargo protocol surface, including the sparse index in both of its path layouts:

The PyPI protocol surface — a PEP 503 and PEP 691 index, plus the legacy upload endpoint twine posts to:

Limits

Two caps apply to publishing, and both are enforced before any bytes are kept.

A file over the size cap is refused with 400 BAD_REQUEST and a message naming the byte limit. A publish that would push the group's namespace past its storage budget is refused with 429 TOO_MANY_REQUESTS. Storage is reserved before the bytes are accepted, so a refusal leaves nothing behind — no orphaned file, no half-created version, and no reservation to reclaim.

There is a second ceiling beside the size cap, and unlike the size cap it does not move with your plan: the registry paths accept a request body up to 512 MiB, and a body over that is refused 413 before the handler sees it. It bites npm first, because an npm publish carries the tarball base64-encoded in a JSON envelope, which inflates it by about a third — a tarball much beyond 380 MiB exceeds the request ceiling and is refused as too large before the per-file cap is ever consulted. Cargo and twine send the artifact as raw bytes, so on the Free tier they meet the 500 MiB cap first; on a plan whose per-file cap is larger than 512 MiB, the request ceiling is the real limit for every format.

There is no cap on the number of packages or versions a registry holds. Stored bytes are the only ceiling, which is why deleting matters and yanking does not: a yank leaves the bytes in place and frees nothing, while deleting a version or a package releases its bytes back to the budget immediately.

Downloads are charged against outbound-byte budgets rather than the storage budget: one for the caller, over the current hour and the current day, and one for the namespace over the current day. When a budget is exhausted, a download answers 429 TOO_MANY_REQUESTS naming the budget that tripped, and because the charge is taken before the redirect is issued, a refusal means nothing was sent at all.

Page sizes are bounded on every paged listing: the packages listing takes 1–100 (default 20), npm search up to 100 (default 20, paged by offset), and Cargo search up to 100 (default 10, paged by 1-based page number). A page size outside its range is clamped to the range rather than refused. The PyPI simple index is not paged: it lists every project at once.

To raise a cap, an Owner of the group can request a limit increase; the alternative is to delete versions nobody depends on. Both the storage budget and the caps in force are visible on the group's usage view.

Troubleshooting

FAQ

Related