How to Pull an Image from GitLab’s Container Registry with Podman or Docker CLI

Pulling images directly from a container repository like those provided by GitLab can be slightly tricky if you are not aware of the correct URL format for podman (Docker equivalent on other platforms). Here’s how to properly pull an image such as alpine:no-root from GitLab’s container registry using either Podman or Docker CLI.

Navigating Registry URLs and Namespaces

The standardized way of accessing the images in a public repository like that provided by GitLab is through their URL: registry.exampledomain.tld. For instance, when you intend to pull an image for GitLab’s own container registry (alpine), using this correct format makes the difference between a successful and failed operation—this applies regardless of whether you’re working with Podman or Docker CLI tools like below:

$ podman pull registry.gitlab.com/gitlab-org/gitlab-runner/alpine:latest  # Using Podman
docker pull registry.gitlab.com/gitlab-org/gitlab-runner/alpine:latest    # And with Docker CLI (equivalent syntax)

Understanding the Format

When examining a GitLab container repository, you might notice an image URL that looks like gitlab-registry://<namespace>/projectname. However, this is not entirely accurate. Here’s what each part of your example means:

1. Registry (https:// or equivalent protocol): The service address where the images are hosted (in our case it would be at GitLab’s domain).
2. Namespace/Project Name Combination: This is a namespace specific to an organization on gitlab—think of this as your team’s project repository within their account space, which can also act like the path in file systems where files are organized (e.g., /home/ directory).
3. **Image Tag/Name: The actual name given by users who maintain or have pushed images into that namespace – think about it similar to naming a specific object (file) within your project space on GitHub, such as my-projectfile in the repository named after yourself with.txt`.
4. For public repositories without authentication requirements (like alpine), you may omit everything before /alpine:

registry.gitlab.com/gitlab-org/gitlab-runner    # Only needed when authenticating is not required for the pull operation: this simplifies your command substantially and works universally across platforms as long as Podman or Docker CLI are installed on them, without any changes to syntax (just prepend `registry.gitlab.com`).

Using Clipboard Icon Trick

As an alternative shortcut method that doesn’t require manually typing out the full URL: simply click a clipboard icon next to image names or URLs within your repository browser, then paste into any shell prompt for immediate use with Podman/Docker CLI. Here’s how it looks visually on GitHub (though GitLab would follow similar user interface conventions):

[Clipboard Icon Cursor] -> registry.gitlab.com/$GITHUB_NAMESPACE/projectname:tag [Click and Paste in Your Command Line Prompt Here for Podman or Docker CLI].

Remember, this method of copying the URL should be used when you’re aiming to pull an image directly into your local environment. Happy containerizing!