Enable the Dependency Proxy for the group in GitLab by navigating to Settings > Packages and registries > Dependency Proxy, or via the Groups API: PUT /api/v4/groups/<GROUP_ID> with dependency_proxy_enabled: true
In CI pipeline jobs, replace docker.io/<image>:<tag> references with <GITLAB_HOST>/<GROUP_PATH>/dependency_proxy/containers/<image>:<tag> to route pulls through the proxy
Authenticate CI runners against the proxy using the predefined CI_DEPENDENCY_PROXY_USER and CI_DEPENDENCY_PROXY_PASSWORD variables in the docker login step targeting CI_DEPENDENCY_PROXY_SERVER
Configure Docker Hub credentials on the group proxy settings to use an authenticated Docker Hub account and avoid anonymous rate limits: set the upstream credentials via Settings or the API
Purge stale cached images using the DELETE /api/v4/groups/<GROUP_ID>/dependency_proxy/cache endpoint to force re-pulls of updated base images
Known gotchas
The Dependency Proxy only caches images from Docker Hub by default; it does not proxy other upstream registries such as ghcr.io or quay.io in GitLab's standard implementation
Token scopes for machine accounts or deploy tokens require read_virtual_registry (pull) or write_virtual_registry (pull and push) — using a token with only registry read access will fail to authenticate to the proxy
Cached image layers are stored per-group and count toward namespace storage quotas on GitLab.com; large base images can quickly exhaust storage limits for free-tier groups
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp