How do I check if an image:tag exists in gitlab container registry

Question

I know that this can be done with dockerhub. I want to know if there is something similar available for gitlab registry.

The use case is that, I have written a fabric script to revert a deployment to a particular tag provided by the user. Before actually pulling in the images, I want to know whether an image with the specified tag exists in the registry and warn the user accordingly.

I've searched in their documentation, but couldn't find anything.

Note: User here is the person who is deploying the code.

Fishy

Check out GitLab 13.0 (May 2020): there is no GUI search for docker images in GitLab. See my edited answer below. – Squirt

Answer 1

Unless the GitLab Container Registry supports the kind of curl dockerhub does (with v1/repositories/$1/tags/$2), I doubt it offers that feature.

(See GitLab 16.7, Dec. 2023, at the end)

For instance, issue 26866 "GitLab Registry available images list/search" is still open after 10 months.

Update for GitLab 12.2 (April 2019, 18 months later)

After working through the implementation, it made sense to create two endpoints:

• GET /groups/:id/registry/repositories - Returns a list of all Docker container repositories for all projects within the group, similar to GET /projects/:id/registry/repositories

and

• GET /groups/:id/registry/repositories/tags - Returns a list of all Docker container repositories for all projects within the group including all tags for each container repository. The response will look something like this:

So that could help checking if an image:tag exists.

---

Update GitLab 13.0 (May 2020)

Use search to quickly find and discover images hosted in the GitLab Container Registry

When you or someone on your team publishes an image to the GitLab Container Registry, you need a way to quickly find it and ensure the image was built properly.
If you’re using GitLab CI/CD to publish images with each build, it’s been very difficult to find an image efficiently within the current user interface. Instead, you’ve relied on the command line or the API.

We are excited to announce that in 13.0, we’ve added search functionality to the GitLab Container Registry.

Simply navigate to your project or group’s registry and enter an image name to see a list of all your images.

See documentation and issue.

---

See also GitLab 14.7 (January 2022)

Sort Docker tags in the Container Registry browser

You can now sort the list of tags in the Container Registry tag details page by name.

Previously, there was no sort functionality. This sometimes required you to scroll through many pages to find a specific tag.

By default, the tags list is now sorted by name in ascending order. You may also change the sort order to descending.
See this issue to track any further work on tag sorting.

See Documentation and Issue.

---

GitLab 16.7 (December 2023) adds:

List repository tags with new Container Registry API

Previously, the Container Registry relied on the Docker/OCI listing image tags registry API to list and display tags in GitLab. This API had significant performance and discoverability limitations.

This API performed slowly because the number of network requests against the registry scaled with the number of tags in the tags list. In addition, because the API didn’t track publish time, the published timestamp was often incorrect. There were also limitations when displaying images based on Docker manifest lists or OCI indexes, such as for multi-architecture images.

To address these limitations, we introduced a new registry list repository tags API. By updating the user interface to use the new API, the number of requests to the Container Registry is reduced to just one. Publish timestamps are also accurate, and there is more robust support for multi-architecture images.

This feature is available only on GitLab.com. Self-managed support is blocked until the next-generation Container Registry is generally available. To learn more, see issue 423459.

See Documentation and Issue.

Squirt

Answer 2

Hint: Also have a look at @filiprafaj's answer using crane.

Ok, here is a solution I came up with using the docker:stable image by enabling the experimental client features.

mkdir -p ~/.docker
"echo '{\"experimental\": \"enabled\"}' > ~/.docker/config.json"
docker  login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY
docker  manifest inspect $IMGNAME:$IMGTAG > /dev/null && exit || true

The exit terminates the build script in case that tag already exists. Also you should be aware that ~/.docker/config.json is overwritten. That is also why the login must happen afterwards.

Update: Instead of writing to the config one can also set the DOCKER_CLI_EXPERIMENTAL environment variable to enabled. Thus the first two lines can be replaced with export DOCKER_CLI_EXPERIMENTAL=enabled

Connelly

Beware you may be using stable but you are still enabling experimental features, of which docker manifest inspect is one – Oilcan

@MarkTickner Yes you are right, yet I don't think that this is a real issue, as while the command line parameters may change, I don't think the functionality will be removed. – Connelly

On Ubuntu 19.04, you get the error “docker manifest inspect is only supported on a Docker cli with experimental cli features enabled”. – Cipher

@TorstenBronger: Did you carefully look at the second line? – Connelly

@morty Yes, I did, but running your mini script gave that error message. – Cipher

@TorstenBronger: That's strange indeed. Are you using a vanilla image or are you doing any magic like changing the user or or other setting? – Connelly

Answer 3

Gitlab API can be used.

tag=tag_name
image=image_name
private_token=gitlab_private_token
project=project_number
repo_id=$(curl --header "PRIVATE-TOKEN: $private_token" "https://gitlab.com/api/v4/projects/$project/registry/repositories" | jq -c --arg regex ".*\\$image$" '.[] | select(.path | test($regex))'.id)

if [ $( curl --header "PRIVATE-TOKEN: $private_token" "https://gitlab.com/api/v4/projects/$project/registry/repositories/$repo_id/tags/$tag" | jq -r '.name' ) == "$tag" ] ; then
  echo "$tag exists"
else
  echo "$tag does not exist"
fi

Ventriloquize

I found that the jq regexp wasn't needed / didn't work, but you can just extract the id key directly like this: repo_id=$(curl --header "PRIVATE-TOKEN: $private_token" "https://gitlab.com/api/v4/projects/$project/registry/repositories" | jq '.[0].id') – Milkman

That is not equivalent though since it ignores $image. Correct should be repo_id=$(curl --header "PRIVATE-TOKEN: $private_token" "https://gitlab.com/api/v4/projects/$project/registry/repositories" | jq '.[] | select(.name==env.image) | .id – Apposite

Answer 4

Crane is a tool that might help. Below is an example, where crane manifest is used inside Gitlab CI/CD Pipeline (.gitlab-ci.yml file).

check_if_image_exists:
  stage: check_if_image_exists
  image:
    name: gcr.io/go-containerregistry/crane:debug
    entrypoint: [""]
  script:
    - crane auth login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
    - if crane manifest $CI_REGISTRY_IMAGE/image:tag; then echo "exists"; else echo "not exists"; fi

Yellowhammer

Just in case someone wonders how to use this in a pipeline: Put Crane's result in an artifact and in the next build-step, build the image based on the the contents of the artifact. – Connelly

Answer 5

So in addition to @fparaggio answer, I was looking for an image if it exist for the current branch, if exist then use the branch image, else use the latest tag as a base image

package:
  stage: package
  image:
    name: registry.gitlab.com/org/hak:kaniko-debug
    entrypoint: [""]
  retry:
    max: 2
  tags:
    - kubernetes
  interruptible: true
  script:
    - if [[ $( curl --insecure --header "PRIVATE-TOKEN:$GITLAB_TOKEN" https://gitlab.com/api/v4/projects/xxx/registry/repositories/xxx/tags/$CI_COMMIT_REF_SLUG | jq -r '.name' ) == "$CI_COMMIT_REF_SLUG" ]] ; then
      echo "$CI_COMMIT_REF_SLUG exists";
      export CODE_VERSION=$CI_COMMIT_REF_SLUG;
      else
      echo "tag for the branch $CI_COMMIT_REF_SLUG => $CI_COMMIT_REF_NAME does not exist, using latest";
      export CODE_VERSION="latest";
      fi

and then pass CODE_VERSION as docker build args

     -  /kaniko/executor
        --build-arg CACHE_IMAGE=$CI_REGISTRY_IMAGE/install
        --build-arg CODE_VERSION=$CODE_VERSION
        --dockerfile $CI_PROJECT_DIR/Dockerfile-release
        --destination $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG

you can find registry ID in the Gitlab UI, no need to make two API call.

https://gitlab.com/org/xyz/repository/container_registry/xxx

Sellingplater