This is another draft that comes from a note I would never publish raw. The original contained a live access token and real registry addresses.

The pattern is still worth keeping, though, because it is a useful way to debug a GitLab container registry endpoint.

1. Start with the Registry API, Not the Docker Client

The note relied heavily on curl against /v2/, and I think that is the right place to start.

A generalized version looks like this:

1
2
3

curl -I https://registry.example.com/v2/
curl -I -H "Host: registry.example.com" http://<registry-ip>:5678/v2/
curl -I --insecure -H "Host: registry.example.com" https://<registry-ip>/v2/

That lets you separate a few questions quickly:

  • is the endpoint reachable at all
  • is the expected host header required
  • are you debugging HTTP, HTTPS, or certificate behavior
  • is the problem authentication or basic routing

2. Keep the Image Naming Path Explicit

The note also preserved the image naming pattern being tested:

1

registry.example.com/group/project/image

That matters because registry path mistakes can look like auth failures at first glance.

3. Validate the Supporting Operational Work Too

The same note also captured backup scheduling and storage mount details around the GitLab host.

That is useful context. Registry work is not only about pushes and pulls. It is also about:

  • making sure the backing storage is mounted where the service expects it
  • taking regular backups
  • cleaning up old backups on schedule

Those tasks are not glamorous, but they are part of operating a registry responsibly.

Closing Thought

This draft still needs another pass before publication, mainly because the original note was so sensitive.

But the main troubleshooting pattern is already worth preserving: when a GitLab registry endpoint looks wrong, start at /v2/ and vary one thing at a time.