List All Docker Images from Self-Hosted GitLab: Complete Guide (2026)

Managing Docker images efficiently is crucial for maintaining a streamlined development workflow, especially when using a self-hosted GitLab server. In this guide, we'll explore how to list all Docker images along with their tags from your GitLab server. This is particularly useful for automating deployments or backups.

Key Takeaways

• Learn how to use GitLab's API to list Docker images.
• Understand how to overcome API pagination limits.
• See practical examples with scripts for automation.
• Troubleshoot common issues related to API calls.

Whether you're a system administrator, a DevOps engineer, or just a curious developer, knowing how to retrieve all Docker images from your GitLab server is invaluable. This tutorial will focus on using GitLab's API to achieve this, highlighting some common pitfalls and solutions.

Prerequisites

• Access to a self-hosted GitLab server with Docker registry enabled.
• Basic knowledge of RESTful APIs and command-line tools.
• GitLab Personal Access Token with appropriate permissions.
• Optional: Basic understanding of shell scripting for automation.

Step 1: Generate a GitLab Personal Access Token

To interact with the GitLab API, you'll need a Personal Access Token with the necessary permissions.

1. Log into your GitLab account.
2. Navigate to User Settings > Access Tokens.
3. Create a new token with read_registry scope.
4. Copy and store the token securely.

Step 2: Understand GitLab API Pagination

GitLab's API returns data in pages by default, with a default limit of 50 items per page. To list all images, you'll need to handle pagination.

For example, to get the first page of images:

curl --header "PRIVATE-TOKEN: your_token" "https://gitlab.example.com/api/v4/projects/:id/registry/repositories"

To retrieve more images, you'll need to iterate through pages using the page parameter.

Step 3: List Docker Images Using GitLab API

Here's a script that lists all Docker images by iterating through all pages:

#!/bin/bash
# Replace these variables with your actual values
GITLAB_URL="https://gitlab.example.com"
PROJECT_ID="your_project_id"
TOKEN="your_token"

# Pagination parameters
PAGE=1
PER_PAGE=50

while true; do
  RESPONSE=$(curl --silent --header "PRIVATE-TOKEN: $TOKEN" \
    "$GITLAB_URL/api/v4/projects/$PROJECT_ID/registry/repositories?per_page=$PER_PAGE&page=$PAGE")

  # Exit the loop if no more repositories are returned
  [[ "$RESPONSE" == "[]" ]] && break

  # Process the response
  echo "$RESPONSE" | jq '.[].name'

  # Increment page
  ((PAGE++))
done

This script uses jq to parse JSON responses, printing the names of all repositories. Ensure jq is installed on your system.

Step 4: List Docker Image Tags

Once you have the repository names, you can list tags for each image:

#!/bin/bash
# Assuming you have the repository names from the previous step
REPOSITORIES=( "repo1" "repo2" )

for REPO in "${REPOSITORIES[@]}"; do
  PAGE=1
  while true; do
    RESPONSE=$(curl --silent --header "PRIVATE-TOKEN: $TOKEN" \
      "$GITLAB_URL/api/v4/projects/$PROJECT_ID/registry/repositories/$REPO/tags?per_page=$PER_PAGE&page=$PAGE")

    [[ "$RESPONSE" == "[]" ]] && break

    echo "$RESPONSE" | jq '.[].name'
    ((PAGE++))
  done
done

This script iterates over all repositories and lists all tags.

Common Errors/Troubleshooting

Some common issues you might encounter include:

• 403 Forbidden: Ensure your token has the correct permissions.
• Rate Limiting: If you make too many requests in a short period, consider implementing a delay between requests.
• Empty Responses: Confirm that the API endpoint URL and project ID are correct.

Understanding these potential pitfalls will help you address them quickly and keep your workflow smooth.

Frequently Asked Questions

Why use the GitLab API to list Docker images?

The GitLab API provides a programmatic way to access and manage Docker images, allowing for automation and integration into scripts and workflows.

How do I handle API rate limits?

Implementing a delay between API requests and ensuring efficient pagination can help manage and mitigate API rate limits.

What permissions are needed for the GitLab Personal Access Token?

The token requires at least 'read_registry' scope to list Docker images and tags.