The GitLab dependency proxy is a pull-through cache for container images stored on Docker Hub. It speeds pulls and reduces rate-limit use. It does not scan or vouch for an image. To keep a build repeatable, pull by digest and scan the image.
What it does
GitLab describes the dependency proxy for container images as a local proxy for frequently accessed upstream images. It caches both the manifest and the blobs of an image, so later pulls can be served without contacting Docker Hub. For tagged images, it checks for staleness only when the manifest becomes stale. It starts requests with a HEAD request, which Docker Hub does not count toward its rate limit, and uses the response digest to see whether the manifest changed.
What it does not do
The page says nothing about scanning content. A cache stores what upstream served. If a tag was moved to a bad image, the proxy can cache that too once the manifest goes stale. Treat it as an availability and speed tool.
| Question | Answer |
|---|---|
| Does it reduce Docker Hub rate-limit use? | Yes |
| Does it cache blobs and manifests? | Yes |
| Does it check an image for vulnerabilities? | No, not on the documented page |
| Does it pin a tag to one image? | No, use a digest |
Authentication
You can sign in with a GitLab username and password, a personal access token, a group deploy token or a group access token. Tokens need read_registry and write_registry, or the virtual registry equivalents. Users need at least the Guest role on the group. Runners sign in to the proxy automatically, using variables such as CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX. Limit token scopes to what the job needs, since a pull needs read scopes.
Steps to use it with care
- Reference images through the group prefix variable in the job
imageline. - Pin to a digest, written as the image name, an at sign and sha256 value, so a moved tag cannot change your build. GitLab's pipeline security guidance says to always use SHA digests for Docker images.
- Avoid variables inside the image reference, since they can be altered to point elsewhere.
- Scan the image before it is used for release builds. See container scans in CI or in the registry.
- Watch storage growth, and note that backups may omit cached files.
Common mistakes
The common error is treating a cache hit as a trust signal. Another is granting write scopes where read scopes would do, since a pull needs only read access. Teams also forget that a proxied tag can still move, so the same tag may give different content a week later. Pin by digest, scan on a schedule, and keep an eye on storage so old layers do not pile up.
Try it yourself
Click through it at your own pace, or open it full screen. Look at the vulnerabilities reported for base image layers, which a cache will not tell you.
Safeguard's dependency and SBOM scanning can show what an image or build contains, and you can try a free scan at https://gold.safeguard.sh/scan.
Quick check
Does the proxy cover npm or other registries?
The page covers images from Docker Hub for containers. Check the current docs before assuming more.
Is pulling latest through the proxy fine?
No. A moving tag changes under you. Pin by digest.
Sources
- GitLab Docs: Dependency proxy for container images, fetched 19 October 2026.
- GitLab Docs: Pipeline security, fetched 19 October 2026.
Last reviewed: 19 October 2026.
