Skip to content

Concepts

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, Release files) is cached for proxy.metadataTtlSeconds (default one hour) and then revalidated with a conditional request.
  • Artifacts (tarballs, wheels, layers, .deb/.rpm files) 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; -1 disables).
  • Outages: if the upstream fails, stale cached content is served. An online: false proxy serves only what it has cached.
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.

  • 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.

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.

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 as npm-*.

Repositories you can’t read are reported as 404 by the API, so their names don’t leak. Details in Authorization.