Concepts
Repositories
Section titled “Repositories”A repository has a unique name, a format and a kind. The name appears in every client URL:
https://entrepot.example.com/repository/<name>/for raw, PyPI, npm, Apt, Yum and Helm,entrepot.example.com/<name>/<image>for Docker (the first path segment is the repository).
Format, kind and blob store are fixed when the repository is created. Other settings can be changed at any time.
| Kind | What it does |
|---|---|
| hosted | Stores what you publish: npm publish, twine upload, docker push, curl -T, the UI or the API. |
| proxy | A pull-through cache of one upstream (proxy.remoteUrl). Content is fetched on first request and served from the blob store afterwards. |
| group | An ordered list of member repositories of the same format behind one URL. Reads try members in order; indexes (PyPI simple pages, npm packuments, Helm index.yaml) are merged. |
How proxies cache:
- Metadata (indexes, packuments, tags,
Releasefiles) is cached forproxy.metadataTtlSeconds(default one hour) and then revalidated with a conditional request. - Artifacts (tarballs, wheels, layers,
.deb/.rpmfiles) never expire by default (proxy.contentTtlSeconds: 0), because they are immutable upstream. - Misses are fetched once even if many clients ask at the same time, and the fetch completes even if the client gives up.
- Upstream 404s are cached for
proxy.negativeCacheTtlSeconds(default 300;-1disables). - Outages: if the upstream fails, stale cached content is served. An
online: falseproxy serves only what it has cached.
Other repository settings
Section titled “Other repository settings”| Setting | Meaning |
|---|---|
anonymousRead |
Anyone can read, without credentials (requires auth.anonymousAccess, on by default). |
hosted.allowRedeploy |
Allow overwriting existing files or versions. Default false, except true for Docker (moving tags). |
group.preferHosted |
npm/PyPI/Helm groups: never take a package name from a proxy member if a hosted member has it. Default true. |
proxy.routingRule |
A routing rule that restricts what is fetched upstream. |
scan |
The repository’s scanning policy. |
cleanup.policies |
Cleanup policies that apply. |
The full list is in the configuration reference.
Components and assets
Section titled “Components and assets”- An asset is one file in a repository: a path, its SHA-256 digest, size, content type, and who stored it and when. A Docker layer, a wheel, an npm tarball and a raw file are all assets.
- A component is a logical package version — a name and a version — that
groups its assets:
lodash@4.17.21,requests 2.32.3, an image tag, a chart version.
Scanning, quarantine and cleanup policies work on components. Search finds
components (GET /api/v1/search); browsing lists assets by path. Assets
uploaded by GitLab CI jobs record the job’s project, ref, commit and pipeline.
Blob stores
Section titled “Blob stores”A blob store is where content lives; Postgres holds only metadata.
| Type | Backing |
|---|---|
file |
A directory on a mounted volume — a PVC on EBS, EFS, NFS or local disk. |
s3 |
An S3 bucket (or MinIO, Ceph RGW, R2) with an optional key prefix. |
Content is addressed by SHA-256 and deduplicated within a store: the same layer pushed to ten images, or a wheel cached by two proxies, is stored once. Unreferenced blobs are garbage-collected. Because every repository picks its own store you can, for example, keep a hot npm proxy on EBS, a large Docker registry on S3 and shared release files on EFS. See Storage & backups.
Identities and permissions
Section titled “Identities and permissions”Every request is authenticated by one chain — browser sessions, Entrepot API
tokens (ent_…), OIDC access tokens, GitLab CI id_tokens, Docker registry
tokens and the bootstrap token. Requests without credentials are anonymous;
credentials that are present but invalid are rejected with 401.
Authorization is role-based:
- Actions:
read,write,delete,admin. - Roles are sets of actions: built-in
viewer,developer,maintainer,admin, plus your own. - Role bindings grant a role to a subject — an OIDC user, a service
account (
sa:<name>), an OIDC group, a GitLab trust policy or everyone authenticated — on repositories matching a glob pattern such asnpm-*.
Repositories you can’t read are reported as 404 by the API, so their names
don’t leak. Details in Authorization.